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At  the  time  Part  T of  this  work  was  being  published,  the  Jet  Propulsion 
Laboratory's  Deep  Space  Network  (DSN)  was  in  the  process  of  developing 
and  writing  a set  nf  Software  Standard  Practices,  for  which  Part  1 was  cited 
as  the  “methodology  textbook/*'  The  standards  were  developed  over  several 
years  by  a group  we  sfmply  called  the  “Software  Seminar/*  It  was  created 
and  chaired  in  its  “pathfinder  period*’  by  Walter  K.  Victor,  who  was,  by  the 
way,  the  significant  inspirator  of  Part  L Mahlor.  F.  Easterling  then  led  that 
syniposium  (second  Webster  [43]  meaning)  through  its  next  “pilot”  phase. 
Edward  C.  Posner  steered  it  through  the  arduous,  major,  final  phase 
involving  detailed  standards  development,  consensus  building,  writing, 
review,  and  publication-  he  also  sponsored  the  final  syinposium  (first 
Webster  [43]  meaning)  immediately  after  the  standards  were  signed  off  by 
upper  management.  Daniel  C.  Freska  administered  the  writing  of  the 
standards,  with  editorial  assistance  by  Richard  C.  Chandlee. 

The  test-bed  for  the  methodologj'  reported  in  Part  t had  been  an  effort  of 
medium  magnitude— a program  (the  M<BASTC^^^  language  processor) 
containing  about  lines  of  non-reabtime  assembly  language  code.  The 

results  of  that  methodolog)'  test-bed  seemed  to  indicate  that  programmer 
performance  better  than  had  been  encountered  in  past  DSN  projects  could 
be  extended  to  the  DSN  as  a whole— an  organization  involving  perhaps  100 
programmers  in  various  disciplines. 

With  that  belief,  the  implementation  team  manager  of  a critical 
hardware/ software  project—to  completely  upgrade  the  digital  data  systems 
in  all  of  the  deep-.spacc  stations  around  the  world— undertook  the  additional 
task  of  applying  and  evaluating  the  then-emerging  DSN  Software  Standard 
Practices  as  a standards-test-bed  activity.  The  overall  project,  including 
software  for  system  performance  tests,  generated  approximately  100,000 
lines  of  hard-real-time  assembly  language  code  over  about  2-1/2  years. 

That  project  could  ill-afford  to  be  a mere  guinea  pig  for  a software 
standards  seminar,  because  the  delivery  of  the  first-phase  system  was 
crucially  tied  to  upcoming  spacecraft  launch  dates  and  committed  on-going 
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missions.  Even  moderjite  deviations  from  the  original  schedule  could  not  be 
tolerated.  Short  slippages  could,  perhaps,  be  accommodated  if  detected 
early  enough  for  appropriate  replanning. 

Yet  the  prospects  for  success  using  the  standards  seemed  good,  A 
software  manager  was  appointed,  cognizant  software  development 
engineers  for  each  of  the  major  assemblies  making  up  the  system  were 
selected,  and  a secretariat  function  (Chapter  17)  was  established. 
Subcontractors  were  selected  to  aid  in  all  activities  of  the  implementation 
and  integrated  with  JPL  persotmel  into  a unified  team.  All  were 
admonished  to  apply  and  conform  to  the  (draft-form)  software  standards  to 
the  maximum  extent,  except  where  it  could  be  shown  that  adherence  to 
standards  was  interfering  with  the  schedule.  Waivers  were  granted  oh  a 
case-by-ease  basis,  in  writings  to  record  the  details  wherein  standards 
proved  ineffective. 


The  project  demonstrated  numerous  gratifying  benefits  arising  from  the 
methodolo^  presented  in  Part  I and  the  more  detailed  standards  contained 
in  this  second  volume.  Among  these  were  good  schedule  and  cost 
performance,  high  product  reliability,  adequate  doGumentation,  increased 
productivity,  and  smooth  development  and  delivery. 

The  delivery  date  did  slip  from  the  original  2-1/2  year  plan  by  somewhat 
less  than  I month  (3%  accuracy  of  original  plan).  However,  this  slip  was 
predicted  about  7 months  in  advance  of  its  actual  oGcutrenGc,  so  that 
effective  contingency  planhing  could  be  initiated.  The  6%  cost  overrun  was 
also  predicted  well  enough  in  idvance  that  reallocation  of  project  resources 
wa.s  effective.  These  excesses  were  considered  unusually  slight,  particularly 
in  comparison  to  past  JPL  experience  and  then-current  industry- published 
data. 

The  software  contained  an  average  of  approximately  3 errors  per 
thousand  lines  of  code,  measured  from  the  beginning  of  system  integration 
tests,  as  compared  to  10-20  errors  per  thousand  lines  commonly  reported 
in  similar  projects  not  employing  top-down  structured  programming 
methodology.  This  te.st  phase,  as  a matter  of  fact,  required  only  about  15% 

the  overall  effort,  whereas  indastry^puhlished  figures  and  previous  JPL 
experience  quoted  about  a 50%  level  of  effort.  The  difference  in  effort  was 
expended  in  the  design  and  planning  phases  to  produce  a more  mature, 
welLdocumented,  reliable  product. 

The  development  and  delivery  were  reported  as  being  smooth  and 
controlled.  No  “tiger  teams'*  were  required  during  implementation,  no 
significant  renegotiation  of  software  commitments  was  needed  near  the  end 
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of  production,  and  the  software  was  delivered  ready  for  operation  with  very 
few  Hens  levied  for  future  corrective  actioa 

The  standards,  of  course,  did  not  accomplish  these  achievements— peopfc 
did»  JPL  was  fortunate  to  have  had  outstanding  personnel  performing  in  an 
exceptional,  professional  manner  throughout  the  project.  All  that  one  may 
claim  for  the  standards  is  that  they  provided  a methodology  which  allowed 
each  member  of  the  project  to  apply  himself  or  herself  toward  the 
accomplishment  of  project  goals  in  the  most  effective  way. 

That  methodolo^  held  up  to  its  promise.  The  managers,  designers, 
coders,  operational  personnel,  documentarians,  and  theoreticians  in  concert 
had  crafted  and  codified  a viable,  detailed  set  of  practices  for  producing 
software.  All  concerned  had  had  a voice  in  the  creation  and  adjustment  of 
their  sofbvare  engineering  disGipline,  and  for  once  the  “horse’*  designed  and 
built  by  a •‘committee”  didn’t  turn  out  to  be  a “camel” 

Part  IT  of  this  monograph,  fhen^  exposes  this  detailed  set  of  rules  for 
software  implementation.  I have  broadened  some  of  the  DSN  practices  in 
some  instances,  in  an  attempt  to  make  them  more  readily  adaptable  to 
organizational  structures  different  than  that  of  the  DSN.  Additional 
consonant  practices  froni  other  sources  have  also  been  incorporated  to 
broaden  the  scope  of  applicability  to  projects  of  types  other  than  the  high- 
technology,  high-efiRciency,  single-purpose,  custom-^built  variety  demanded 
by  the  deep-space-station  environment. 

There  are  many  whoiii  T must  thank  aiid  acknowledge  for  their  many  and 
various  contributions  toward  the  completion  of  this  second  volume, 
Robertson  Stevens,  the  former  manager  of  a large  computing  facility  and, 
during  this  time,  manager  of  the  upper-level  organization  containing  the 
hardware/software  project,  was  the  propounder  of  many  of  the  manage^ 
ment  policies  and  status  monitors  that  are  found  in  this  work,  Paul  T. 
Westmoreland  was  the  manager  of  the  implementation  project;  his 
professionalism,  ability  to  manage,  faith  in  a standardized  approach^  and 
courage  to  commit  that  approach  to  a cititieal  task  have  been  a personal 
inspiration. 

I must  also  acknowledge  the  effectiveness  of  Alvin  F.  EUman  of  the 
Bendix  Corporation,  who  was  software  manager.  Tt  was  perhaps  AVs  ability 
to  recognize  what  quantitative  information  a programmer  eoiild  communi- 
cate naturally  to  management  and  others  that  led  to  the  refined  status 
monitors  that  proved  so  effective.  His  abilitj^  to  relate  to  and  interface  with 
project-internal  programmers  and  project-external  systems  engineers  and 
users  was  a major  factor  in  an  organization-vdde  feeling  of  confidence  in 
the  health  of  the  growing  and  maturing  .software* 
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The  subsystem  Cognizant  Development  Engineers  were  Robert  Desens, 
Frank  Hlavaty,  Ronald  Murray,  Gary  Osborn,  and  St^e  Yee.  Observance  of 
their  applications  of  the  standards  and  their  performance  under  the 
standards  produced  many  refinements  for  effectiveness. 

The  members  of  the  DSN  Programming  System  Steering  Committee 
included,  at  various  times,  Walter  K.  Victor,  Robertson  Stevens,  Mahlon 
Easterling,  Lee  W.  Randolph,  Carl  W.  Johnson,  Cecil  P.  Wiggins,  Edward 
C.  Posner,  Malvih  L.  Yeater,  William  C.  Frey,  William  t>,  Hodgson, 
Angela  Irvine,  Raul  D.  Rey,  Richard  B.  Miller,  and  Donald  L.  Gordon.  Each 
made  special  contributions  too  numerous  to  single  oiit. 

R.  Booth  Hartley  and  Lawrence  R.  Hawley  were  both  co-developers  and 
appliers  of  the  rules  given  here  during  the  various  implementations  of 
elements  of  the  DSN  Programming  System.  Their  support,  feedback,  and 
ability  were  sorely  needed  and  freely  provided  during  the  preparation  of 
this  material.  Kay  Landon  and  Leonard  Benson  proofread  Part  1 and 
generated  its  index;  they  also  progammed  a prototype  CRISPFLUW 
processor,  leading  to  the  descriptions  in  Appendix  G,  Annamarie  Grana 
helped  evaluate  the  utility  of  Appendix  C,  using  it  as  a guide  for  Mi.': 
generation  of  two  SRDs.  Frank  Hlavaty  collaborated  in  the  formation  of 
Appendix  E.  Michelle  Martin  and  Marshall  Polsley  contributed  to  the 
format  and  content  of  Appendix  X.  Richard  Schwartz  s iniiuence  is 
prevalent  in  the  standard  language  discussions  in  Chapter  17.  John  Johnson 
and  Henry  Kleine  were  instnimental  in  the  formation  of  the  CRISP 
language. 

I give  special  thanks  to  Georgiana  Clark,  who  typed  and  corrected  the 
entire  manuscript;  to  Carol  Rosner,  who  had  typed  a preliminary  draft  of 
the  first  five  chaptersi  to  Margaret  Seymour,  who  drafted  all  the  figures 
except  those  in  Appendices  G and  L;  to  Silvia  Munoz,  who  aided  in 
generating  the  index;  to  Harold  Yamamoto,  who  edited  the  volume  for 
publication;  and  to  Doris  Peny,  who  coordinated  all  the  artwork  and  was 
responsible  for  the  final  page  makeup.  T also  extend  a belated  thanks  to 
Anita  Sohus,  who  coordinated  all  the  artwork  for  Part  T. 

Finally,  T wish  to  thank  those  who  have  participated  in  the  many 
seminars  and  classes  given  on  this  material  during  its  various  stages  of 
Gompletioii;  many  insights  iiito  the  secrets  of  software  engiiieeriiig  across  a 
broad  programmer  base  were  revealed  to  me  as  the  result  of  these 
interactions. 


Robert  C,  Tausworthe 
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STANDARDS 


XI.  SOFTWARE  REQUIREMENTS  AND 
DEHNinON  STANDARDS 


This  chapter  is  the  first  of  a set  co.ntaining  specific  standards  extracted 
from,  or  generated  in  response  to,  the  methods  presented  in  Part  L These 
are  the  rules  that  guide  the  top-down^  hierarchic,  modular,  structured 
approach  to  software  development. 

There  arc,  of  course,  no  universal  rules  to  make  intricate  programming  a 
simple  task,  and  there  is  perhaps  very  little  hope  of  ever  completely 
formalizing  the  programming  process.  Design  is  a creative,  inventive  craft. 
But  merely  identifying  the  constraints,  objectives,  design  tools,  and 
parameters  in  a standardized  way  yields  considcraBi?  progress  in  dealing 
with  problem.^  eifcctively.  Furthc  'more,  these  standard  procedures  can  be 
taught.  Referenees  [1]  through  [6]  are  examples  of  standards  in  eflFeet  based 
on  the  methodology  reported  here. 

The  standards  and  practices  contained  in  the  remainder  of  this  work  are 
meant  primarily  to  apply  to  new  programs  or  major  extensions  to  existing 
programs  intended  for  operational  use.  They  are  meant  to  be  easy  to  use,  to 
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2 Sojkwure  Requirements  and  Definition  Staridards  [CHAP,  11 

he  somewhat  flexible^  and  to  provide  guidelines  for  foeusing  the  activities 
toward  what  is  most  needed. 

The  use  of  a consistent  outline  and  format  for  documenting  each  activity 
is  presumed.  The  outlines  in  Appendicos  C,  D>  and  E contain  a detailed  set 
of  topics  to  be  considered  in  donning  the  requirements  and  functional 
behavior  of  a software  package.  The  topics  also  give  guidelines  as  to  what 
material  is  to  be  specified  within  each  topic. 

A large  portion  of  any  software  engineering  activity  deals  fundamentally 
with  the  planning  of  a software  development,  rather  than  the  actual  doing 
of  it  T recognize  that  a discipline  for  such  planning  is  needed  just  as  much 
as  a discipline  for  doing,  so  T have  oriented  the  rules  given  here  toward  the 
more  technical  aspects  of  project  engineering  and  software  development 
The  interested  reader  wishing  to  delve  more  deeply  into  nianagement  and 
planning  disciplines  may  consult  [1]  through  [ 11]. 


11.1  GENERATING  SOFTWARE  REQUIREMENTS  \ 

\ 

A software  requirement  is  a need  established  for  a piece  of  software  by 
an  organization  in  order  to  achieve  certain  goals.  The  requirement- 
generation  activity  culminates  in  the  approvals,  negotiations,  and 
commitments  oi*  resources  necessary  to  initiate,  sustain,  and  complete  the 
.software  development.  Although  1 have  not  considered  requirements 
generation  in  past  chapters  to  be  among  the  software  development 
activities,  nevertheless,  there  are  a few  guidelines  that  can  make  the 
generation  of  softw'ure  requirements  more  uniformly  responsive  to  the 
needs  of  oncoming  activities. 

The  Software  ftequireinents  Document  (SRD)  is^  relatively  speaking,  a 
non-technical  document;  in  its  first- reviewed  form,  it  probably  contains 
only  enough  functional  and  technical  information  and  requirements 
{perhaps  by  reference)  to  identify  the  need  for  a perhaps  intangible 
capability.  At  this  point,  its  content  is  primarily  oriented  so  as  to  allow  the 
authorizing  organization  to  determine  what  it  is  approving. 

Part  of  this  approval  involves  the  expenditure  of  resources  to  permit  the 
requirers  (and,  later,  impleriientors)  to  supply  more  planning  information 
and  technical  detail 

Requirements  are  only  definite  to  the  extent  that  they  are  documented. 
The  needed  output  of  the  requirement-generation  activity  is  an  SRD 
satisfying  the  following  criteria  (see  Section  3,3): 
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a.  It  should  be  adequate  to  identify  the  objectives  of  the  program,  its 
environment,  the  configuration  needed  for  its  operation,  the  rcsouiiecs 
required  for  its  support,  and  the  advantages  and  disadvantages  in  the 
service  it  provides,  us  related  to  the  customer  organization. 

b.  It  Shoiild  he  adequate  to  permit  the  developmental  activities  to 
proceed  under  a rcasoiiable  assurance  that  major  revision  of 
requirements  will  not  be  necessary. 

c.  It  should  be  adequate  for  review  and  approval  by  cognizant  authority 
on  the  basis  of  its  conceptual  feasibility  in  accordance  with  the  other 
criteria  above.  It  should  contain  manpower,  sehedules,  and 
developmcnt-GQSt  estimates,  as  well  as  reasonable  variances  for  these 
estimates,  at  least  for  the  next  phase  of  activity. 

As  I indicated  in  previous  chapters,  it  may  not  always  be  feasible  to 
actually  complete  the  SRD  until  after  some  of  the  software  development 
process  has  already  begun  (in  a top-down  way,  of  course).  That  part  upon 
which  the  funding  and  manpower  approvals  are  based  (the  overview) 
probably  derives  in  largest  part  from  the  justification  section  (see  Appendix 
C).  This  justification— intended  for  rhahagement— contains  material  oriented 
principally  toward  establishing  the  need  for,  and  feasibility  of,  software  to 
fulfill  certain  goals  or  missions  of  the  funding  organization. 

The  remainder  of  the  SRD— for  guiding  the  implementation— deals  with 
setting  forth  technical  requirements,  deyelopmental  cons’traints,  arid 
acceptance  criteria  in  enough  detail  to  identify  the  exterb'^d  functional  and 
operational  characteristics  of  the  software.  These  eaii  subsequently  be 
negotiated,  refined,  and  then  implemented  so  as  to  satisfy  the  sponsor  s 
goals.  The  final  SRD  constitutes  aii  agreement  betweeti  the  requesting  and 
implementing  organizations  on  the  software  to  be  produced. 

Tile  SRD  contains  material  that  may  well  be  broken  into  several  separate 
clocurrients,  such  as,  perhaps,  a Software  Justification  Report,  a Software 
Acquisition  Plan,  a Software  Fimetional  Requirement,  and  so  on.  Some 
material  may  he  included  directly,  if  not  extensively,  while  some  may  be 
appended  or  referoncedi  The  hierarchic  nature  of  the  outline  in  Appendix  C 
permits  this  to  be  done  quite  easily  in  the  most  accommodating  way, 
should  the  need  arise. 


The  reader  may  notice,  comparing  Appendices  C,  D,  and  E,  that  the 
SRD,  Software  Design  Definition  (SDD),  and  Softvvare  Specification 
Document  (SSD)  outlines  are  all  very  sirriihir  in  appearance.  But  Vv^'hile  they 
cover  the  same  general  topic,  they  do  hot  generate  the  saine  Gontent,  The 
SRD,  upon  completion,  contains  customer/user  requirements  and 
coastraints,  and  estimates  tlie  resources  available  or  needed  for  software 
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projdiiction.  The  SDD  Identifies  those  external  charaeteristi-cs  of  a program 
needed  to  fulfill  the  given  requirements^  establishes  the  program 
architecture,  defines  cost*  and  schedules,  and  presents  a work  breakdown 
structure  by  tasks.  The  SSD  defines  the  external  and  Gperational 
Gharacteristios  of  the  program  and  specifies  how  these  are  to  be  efiPected 
into  internal  program  structures,  “as  built/'  By  giving  these  documents  the 
semblance  of  a conformable  outline,  T have  tried  to  ensure  a rough 
downward  traceability  from  pre-design  requirement  to  definitiGns,  to 
implemented  specifieatiGns,  and  upward,  again,  in  the  reverse  order. 

11.1.1  Rules  for  Generating  Software  Requirements 

The  following  giiidelines  for  striicturing  software  requirements  form  a 
sipall  set  of  standards  to  aid  in  the  preparation  of  the  SRD  through  the 
overview  phase,  Gulminating  in  a Requirements  Review.  Sections  3.1  and 
3.2  contain  useful  guidelines  for  recognizing  requirements. 

1,  Complete  the  SRD,  supplying  the  material  indicated  in  the  topical 
outline  (Appendix  C),  documented  subject  to  the  rules  in  SeCtior  11.4. 


Delete  items  in  the  outline  that  are  irrelevant  or  do  not 
apply,  or  mack  them  as  “not  applicable/'  Mark  purposely 
iinspeeified  items  as  “development  prerogative/'  perhaps 
ronditioned  by  the  addition  of  modifiers,  such  as  “subjeet 
to  approval/'  Cite  existing  material,  such  as  poliGies  and 
constraints,  by  reference*  inckide  deviations  from  these, 
however.  Figure  11-1  presents  a graphic  table  of  contents 
for  the  SRD  tlut  emphasizes  the  hierarchy  of  management 
information.  The  CGinplete  graphic  table  of  eontents  is 
shown  as  Figure  C-1  (Appendix  C). 

2.  Establish  a set  of  criteria  and  weights  for  the  SRD  review,  such  as 
breadth  of  coverage,  level  of  detail,  adherence  to  standards,  etc.,  and  obtain 
conGurrence  on  these  from  the  review  board 

3.  Identify  cost  and  schedule  drivers  likely  to  impp.Gt  the  decisions  that 
have  to  be  made.  Establish  priorities  and  constraints  for  developniont,  with 
emphasis  placed  on  factors  that  tend  to  drive  costs  up  if  they  are  not 
identified  and  frozen  early. 

Include  any  known  factors  involving  special  eomplexlty 
that  tend  to  jeopardize  schedules  or  place  stringent 
demands  on  specific  (and  possibly  scarce  or  unavailable) 
personnel. 


SPQ 


ScG.  llJi  Generating  Software  Requirements 


ICMAP.  12 


6 Software  Requirements  arid  Definition  Stnndards 

4,  Identify  and  summarize  or  reference  the  functional  processing  of 
inputs  required  to  obtain  the  proper  outputs.  Define  user/customer 
technical  requirements  only  down  to  that  degree  of  detail  beyond  which  no 
major  influence  on  resources,  schedule,  or  programmatic  requirements  is 
typically  felt 

State  specific  iriput/output  formats,  details  on  internal  or 
external  data  structures,  computer  internal  operations,  etc., 
only  if  they  do  exert  a major  influence  on  development 
Generate  and  append  requirements  not  in  this  categoiy, 
but  needed  by  implementors,  as  later  detailed  Functional 
Requirements^ 

D.  Tdontify  existing  kiiown  capability,  technology,  or  routines  that  may  be 
used  (directly  or  with  modification),  especially  if  the  existence  of  these  can 
have  a great  impact  on  cost  or  schedule; 

6.  Identify  and  rank  charaeterisiics  that  compete  for  development 
resources.  First-  and  seeoiid-order  doHiinances  (Appendix  L)  are  usefti!  for 
this  purpose.  Qualify,  as  appropriate,  any  conditions  that  may  alter  this 
ranking, 

7.  Identify  organizations  or  individuals  (if  known)  to  be  involved  in  the 
impiementation^  operation,  and  use  of  the  software,  and  state  the  roles  of 
each. 

8.  Establish  criteria  for  evaluating  implementation  team  performance 
and  for  program  acceptance  and  delivery. 

9.  Determine  schedules  and  cost  bounds.  Estimate  the  relative  values  of 
required  capabilities  and  available  resources  that  can  be  applied  toward 
delivery  within  these  bounds. 

For  example,  the  earlie.st  date  that  the  software  can  be 
accommodated,  if  delivered;  the  latest  operational  date 
software  can  be  delivered  without  serious  degradation  of 
the  project  goals;  etc.  Include  possible  conflicts  between 
this  activity  and  other  ungoing  work.  This  cost/time 
schedule  is  not  intended  to  define  p day-to-day  work  planj 
but,  instead,  to  establish  a baseline  for  needed  capability, 
to  be  refined  in  the  next  phase  (the  architectural  de'^ign);  ' 
based  on  more  detailed  considerations. 

10.  Prioritize  technical  requirements  so  as  to  accommodate  the  .schedule 
and  cost  bounds. 
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For  example,  require  ptogram  modes  that  will  permit, 
perhaps,  a degraded,  hut  aeceptable,  paitial  performanee 
during  mission  operations  if  delivery  is  late. 

11,  Prior  to  the  actual  SRD  review,  gt^de  the  SRD  relative  to  review 
criteria  and  weights  established  in  Rule  2,  above,  to  gauge  the  pre-review 
quality  of  the  SRID,  After  the  review  presentation,  urge  the  review  board 
likewise  to  grade  the  SRD. 


12,  Obtain  management  approval  (at  least  informally  or  in  principle) 
before  proceeding  to  the  next  phase  {the  actual  software  development 
activity).  Approval  signatures  should  be  those  required  by  the  normal 
organizational  procurement  policy,  based  on  the  estimated  program  cost, 
even  if  the  work  is  to  be  performed  in-house. 

13,  If  iterations  or  negotiations  of  requirements  are  necessary  after 
approvals  were  obtained  in  order  to  complete  the  SRD,  infdrin  the  board- 
convening authority  for  possible  re-^rwiew  if  there  are  major  redireetions  or 
Gost/scheduile  impacts, 

14,  Do  not  release  any  requirements  for  formal  design  and  coding  iintil 
these  have  been  approved,  with  concurrence  from  the  implementor. 


11.2  GENERATION  OF  THE  SOFTWARE 
ARCHITECTURAL  DESIGN 


Once  a set  of  requirements  has  reached  the  implementing  organization, 
the  implementor  ' nters  upon  a design  feasibility  study,  translating  the 
requirements  given  in  the  SRD  into  a definition  of  the  needed  design,  the 
scope  of  work,  refined  eost/schedule  estimates^  and  project  organizational 
activities.  This  phase  of  the  software  definition  activity  culminates  in  a 
Software  Design  Defir-ition*  (SDD),  which  displays  the  program  and 
development  team  architecture. 

This  activity  can,  and  probably  should,  take  place  in  concert  with  the 
generation  of  some  of  the  later,  more  detailed,  technical  software 
requirements.  Much  of  the  SDD  may  even  have  to  be  developed  as  iihe 
SRD  is  being  completed,  as  a cooperative  interaction  between  initiator  and 
implementor. 


’^‘'This'clocurncrit;  Is'  termed  the  SbftArurc  Definition  Document  In  the  JPL  iioftware  Standards, 
cited  ln  [i]  through  [6j. 
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The  SDD  is,  as  was  the  SRD  before  it,  largely  non-teehnieah  in  that  it 
contains  a lot  of  planning  information— this  time  from  the  implementor's 
point  of  view,  It  does,  however,  contain  enough  technical  detail  (perhaps 
by  reference)  to  cany  the  program  functional  and  internal  behavioral 
speGifications  to  the  point  of  strueturing  the  remainder  of  the  development 
task  according  to  the  following  criteria: 

a.  It  defines  the  manner  in  which  the  program  and  its  technical 
documentatiGn  shall  respond  to  each  of  the  requirements  in  the  SRD. 

b.  it  should  be  adequate  to  permit  the  remainder  of  the  developmental 
activities  to  proceed  under  a reasonable  assurance  that  a n^ajor 
re\dsiou  of  the  program  architecture  will  not  be  necessary, 

e.  ft  should  be  adequate  for  review  by  teehnicai  authority  and 
management  on  the  basis  of  its  technical  feasibility  and  the  soundness 
of  its  manpower,  budgetaiy,  and  eost/sehedule  estimates, 

A Gaildidate  outline  for  an  SDD  appears  graphically  in  Figure  11-2  and 
more  detailied  in  Appendix  D.  The  rules  for  completing  the  SDD  represent 
a bridge  between  those  for  the  SRD  and  those  for  the  detailed  Software 
Functional  Specification,  dfesGribed  in  Section  li,3,  and  those  for  the 
Programming  Specification,  the  subject  of  Chapter  12, 


11.2.1  the  Work  Breakdown  Structure 

The  Work  Breakdown  Structure  (WBS)  is  an  enumeration  of  all  work 
activities  in  hierarchic  refinements  of  detail,  which  organizes  work  to  be 
done  into  short,  manageable  tasks  with  quantifiable  inputs,  outputs, 
schedules,  and  assigned  responsibilities.  It  may  be  used  for  project 
budgeting  of  time  and  resources  down  to  the  individual  task  level,  and  as  a 
basis  for  progress  reporting  relative  to  meaningful  management  milestones, 
A software  management  plan  based  on  a WBS  contains  the  necessary  tools 
to  estimate  costs  and  schedules  accurately  during  the  architectural  phase, 
and  to  provide  visibility  and  control  during  production. 

Such  a plan  is  structured  to  evaluate  technical  accomplishment  on  the 
basis  of  task  and  activiiy  progress.  Schedules  and  networks  (see  the  first 
example  of  Appendix  L)  are  built  upon  technical  activities  in  terms  of  task 
milestones  (i.e.,  aceomplishments,  outputs,  and  other  quantifiable  u:ork 
elements).  Projected  versus  actual  task  progress  can  be  reviewed  by 
technical  audit  and  by  progress  reviews  on  a regular  (say,  monthly  or  bi- 
weekly) basis.  Formal  Project  Design  Reviews  are  major  check  points  in 
this  measurement  system. 

How  refined  should  this  WBS  be?  Let  me  answer  this  question  by 
showing  how  the  WBS  and  schedule  projection  accuracy  are  interrelated. 
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if  a project  has  identified,  say,  during  its  arehiteeturd  design  phase,  a 
certain  number  of  equi-effort  milestones  to  be  achieved  during  the  course 
of  development,  then  the  mere  number  of  milestones  achieved  by  a certain 
date  is  an  mdicator  of  the  progress  toward  that  goal.  A graph  of 
accumulated  milestones  as  a function  of  time,  sometimes  called  a '*rate 
chart,”  permits  certain  predictions  to  be  made  about  the  future  completion 
date  rather  handily  and  with  quantifiable  accuracy,  especially  if  the 
milestones  are  chosen  properly. 

Let  us  suppose  that  it  is  known  a priori,  as  a result  of  generating  the 
WBS,  that  a project  will  be  completed  after  M milestones  have  been  met. 
These  milestones  correspond  to  ail  of  the  tasks  that  have  to  be 
aceomplished,  and  once  accomplished  are  accomplished  forever  (i.e,,  some 
later  activity  does  not  re-opeh  an  already  completed  task;  if  such  is  the 
case,  it  can  be  accommodated  by  making  M larger  to  include  all  such 
milestones  as  separate  events).  The  number  M,  of  course,  may  not  be 
precisely  known  from  the  first,  and  any  uncertainty  in  M is  certainly  going 
to  affect  the  estimated  eompletion  diate.  This  can  be  factored  in  as  a 
secondaiy  effect  later,  as  needed  for  refinement  of  accuracy. 

Now,  let  lis  further  suppose  that  it  has  been  possible  to  refine  the  overall 
task  into  these  M milestones  in  such  a Way  that  each  task  is  believed  to 
require  about  the  same  amount  of  effort  and  duration  to  acGomplish. 
Viewed  at  regular  intervals  (e,g,,  bi-weekly  or  morithly),  a plot  of  the 
cumulative  numbers  of  milestones  reported  as  having  been  completed 
should  rise  linearly  until  project  completion  (Figure  11-3). 

More  quantitatively,  let  the  reporting  period  interval  be  denoted  T;  let  n 
denote  the  most  optimistic  ^but  realistie,  if  all  goes  well)  number  of 
milestones  (constant  each  AT  period),  which  can  be  completed  in  AT  days; 
let  m be  the  average  number  actually  completed;  and  let  q = 1 — (m/n). 
The  last  value,  q,  is  the  WBS  deviation  factor  inherent  in  the  WBS. 

The  value  of  m is  a reflection  of  the  team  productivity  and  q is  a 
measure  of  their  ability  to  keep  up  with  an  optimistic  version  of  the 
schedule.  Both  are  attestations  to  team  effeGtiveness^first,  in  their  ability  to 
produce,  and,  second,  in  their  ability  to  create  a work  plan  that  adequately 
aecourits  for  contingencies.  It  is  important  to  strers  that  q does  not  in  any 
way  reflect  on  a team  s ability  to  produce;  it  is  merely  a measure  of  how 
much  the  WBS  depends  on  everything  going  well.  Low  values  of  q show 
low  deviations  from  optimistic  performance  inherent  in  WBS  formation, 
that‘s  all. 

The  project  with  a given  productivity  should  require  a time  (M/m)AT  to 
complete,  which  time,  of  course,  should  not  depend  on  whether  a WBS  was 
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Figure  11^.  Cumulative  mileetohes  achieved  as  a function  of  time  (caae  illustrated  has 
parameters  p = 1 - q,  h - 10^  p = 2/3,  M = 4Q) 

made  or  not  (l  am  discountings  in  this  discussion,  whether  WBS  generation 
incre^^es  or  decreases  productivity).  Thus,  M/m  should  be  a constant  value, 
relatively  speaking.  If  M is  made  large,  tasks  are  smaller  and  shorter,  so 
proportionately  more  of  them  are  completed  each  MV  reporting  periods 
The  original  project  schedule  will^  in  fact,  assume  some  produotivify,  or 
mean  aceomplishmeht  ratCj  but  an  actual  performance  value  is  generally 
unknown  until  progress  can  be  monitored  for  some  period  of  time. 

But  while  the  numbers  M and  q may  not  afiect  the  team  productivity, 
they  do  directly  influence  the  efFectiveness  with  which  a project  can 
monitor  its  progress  and  predict  its  future  accomplishments.  Generation  of 
a WBS,  of  course,  gives  the  parameter  Monitoring  the  completion  of 
milestones  provides  estiniates  for  m and  q.  From  these,  projections  of  the 
end  date  and  calculations  for  the  aceuracy  of  this  prediction  can  be  made. 
Based  on  such  information,  the  project  can  then  divert  or  reallocate 
resources  to  take  corrective  action,  should  progress  not  be  deemed  suitable. 


A best  straight-line  fit  through  the  cumulative  milestone  progress  over 
the  first  r reports  (of  an  expected  R = M/m  reports)  at  AT  intervals  will 
predict  the  time  Tf^  to  reach  the  final  milestone.  It  will  also  provide  an 
estimate  of  m and  q.  The  predicted  completion  date  may  be  expected  to 
deviate  from  the  projected  value  (as  a one-sigma  event)  by  no  more  than  [7] 

rms(TM)  ^ L48(q/M)l^^2(R/r)l/2Tj^ 
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within  first-order  effects.  This  bound  permits  the  specification  of  WBS 
characteristics  that  enable  accurate  early  prediGtions  of  future  p^ogre^’s. 
The  botmd  above  shows  that  high  accuracy  depends  on  having  u low  q/  M 
ratio.  Therefore,  one  must  be  tc///mg  to  pay  for  WAS  optimism  at  the  cost 
of  generating  and  monitoring  progress  relative  to  a more  detailed  WBS, 


As  an  example,  suppose  that  a 10%  end-date  prediGtlon  aceuracy  is 
required  by  the  end  of  the  first  quarter  (r/R  = G.25)  of  a project  Then  the 
milestonc/optimism  tradeoff  factor  acGording  to  the  bound  above  is  M/q 
870^  hencei  if  the  WBS  is  highly  optimistic  (q  ==  l),  that  WBS  should 
Gontain  876  equi^luration  iniltestones!  If  the  project  is  confident  that  it  can 
hold  more  closely  to  its  optimistic  schedule  (has  most  contingencies 
provided  for)^  with  a q «=  0.25,  then  it  needs  only  about  220  milestones,  A 
one-man-year  project  with  bi-weekly  reporting,  one  milestone  per  report 
(26  milestones  in  allj),  must  demonstrate  a q = 0*0.1  deviation  factor!  Less 
than  one  milestone,  on  the  average,  can  be  m issed! 

Perhaps  this  is  a sad  realization  to  some  readers^  but  it  is  almost  certainly 
a fact  The  model  for  these  figures  may  be  held  suspect,  but  let  me  say  it  is 
based  on  very  conservative  assumptions.  It  is,  therefore,  both  necessary  and 
important  to  generate  a detailed  WBS  rather  carefully,  and  to  monitor 
milestone  achievements  relative  to  this  WBS  very  faithfully,  if  accuracy  in 
predieting  the  future  progress  of  a project  is  of  great  importance, 

11.2w2  Buies  for  Generating  the  Software  Design  Definition 

Many  of  the  rules  to  be  applied  in  generating  the  architectural  design  are 
the  same  as  those  previoiisly  given  in  Section  11,1*  therefore,  T will  not 
repeat  them  here.  The  reader  should,  however,  apply  them  when  entering 
upon  the  generation  of  an  SDD,  but  orient  them  toward  the  criteria  in 
Section  11,2,  above.  The  reader  should  also  consult  Sectioris  12.1  and  12,2 
in  the  next  chapter  for  additional  guidelines  toward  the  architectural  design 
of  internal  program  procedures. 

1,  Complete^ the  SDD,  supplying  the  material  indicated  in  the  topical 
outline  (Appendix  D),  documented  subject  to  the  niles  in  Section  11,4  and 
Chapter  16,  according  to  the  specific  eases  being  dDCiimented. 

Delete  items  in  the  oritline  that  are  irrelevant  or  that  do 
not  apply,  or  mark  them  as  "not  applicable,”  Mark 
purposely  unspecified  items  as  "later  design  prerogative," 
perhaps  conditioned  by  the  addition  of  modifiers  such  as 
"subject  to  approval,”  Cite  existing  material,  such  as 
Standards  and  Conventions,  by  reference  only;  include 
deviations  from  \these,  however.  Figure  11-2  illustrates  the 
format  of  the  SDD. 
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2*  Characterize  the  goals  of  the  program  development  in  terms  of 
priorities  among  reliability,  maintainability,  modifiability,  generality, 
usability,  and  efiBGicncy. 

3.  Provide  a top-down  structured  conceptua!  design  that  depicts  the  step- 
by-step  decomposition  of  the  program  into  its  major  modes,  suhfiinctions, 
and  algorithms.  Document  this  design  in  a form  suitable  to  later  cariy  on 
the  formal  top-down  detail^  design  (SSD  phase). 

In  some  instances,  hand^rawn,  properly  annotated  flow- 
charts or  GRTSP-PDL  will  suffice.  In  such  cases,  the 
program  architects  need  not  be  o^^erly  concerned  with  the 
detailed  correctness  of  procedures,  so  long  as  the  basic 
architecture  is  sound  enough  for  cost  and  schedule 
estimates,  The  flowcharts  themselves  are  no^ally  not  a 
part  of  the  SDD,  but  an  overview  of  the  architecture  is. 

4.  Set  work  assignments  and  team  interfaces.  Choose  these  assignments 
so  as  to  minimize  the  iinplicatfons  of  human  and  program  interfaces  (see 
Chapter  10)  and  to  maximize  module  inner  cohesion  (Chapter  4). 

5.  Design  tlic  major  data  stnictures  and  program  data  bases  to  the  extent 
needed  to  establisli  the  program  architectiire. 

Specifically,  leave  to  the  detailed  specification  phase  all 
GGnsiderations  that  do  not  directly  respond  to  the  SRD  or 
that  do  not  impact  cost  and  schedule  fn  a significant 
manner. 

6.  Couple  the  development  of  the  SDD  to  any  concurrent  efforts  toward 
completing  the  SRD  or  toward  development  of  the  SSD^ 

7.  Determine  how  requirements  shall  be  met  by  design  and  how  each  of 
the  design  items  shall  be  prioritized  to  accommodate  requirements. 

Specifically,  identify  requirement  not  being  responded  to, 
or  conflicts  or  changes  in  priorities,  schedules,  etc.  Figure 
11-4  illustrates  one  such  method  of  illustrating  how 
requirements  will  be  accommodated. 

8.  Determine  refined  cost  and  schedule  estimates  based  on  a Work 
Breakdown  Structure  of  tasks  using  the  architectural  design  as  a model  for 
the  estimation^  Give  variances  or  tolerances  for  each  item  estimated,  and 
combine  these  iiitb  overall  tolerance  estimates  for  the  costs  and  schedule.  If 
a toleranec  goal  has  been  given,  refine  the  architecture  and  cost/schedule 
estimates  until  the  goal  is  met 
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FlguM  114.  A ftHTii  for  demonstrating  the  eccommodatton  of  requirements  and  priority 
(shown  m Archttecturai  besfjgn  Review) 


9.  Limit  the  program  areh^**:ectural  phase  of  aetivity  to  that  level  of  detail 
required  to  fix  costs  and  schedule.  Tf  additional  architectural  details  are 
required*  develop  these  as  part  of  the  formal  design  phase. 

10.  Orient  the  Work  Breakdown  Structure  toward  measurable  milestones 
that  Gan  be  reported  upon  completion.  Account  for  the  possibility  that 
certain  tasks  will  need  to  be  repeated,  and  include  contingeiiGies  as  separate 
tasks  when  appropriate. 


11,3  GENERATING  THE  SOFTWARE  FUNCTIONAL 
SPECIFICATION 


The  funGtionai  speeifieatiGn  activity  is  primarily  eoncerned  with 
describing  the  detailed  end-rto-end  characteristies  of  the  program*  without 
too  much  concern  i wer  what  goes  on  in  the  middle  (except  as  may  emerge 
due  to  confUels  betveen  these  definitions  and  what  the  conGurrent  design 
effort  has  been  able  to  support).  Generating  a set  of  functional 
specificatiGns  is  at  as  demanding  a task  as  designing  the  program  they 
deseribci  and  specifications  are  just  as  likely  to  be  in  error.  Becaiise 
specifications  cannot  be  “run/’  there  is  a tendency  to  postpone  writing 
them  until  later*  when  there  is  a program  that  can  be  run.  For  many 
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reasons  such  an  approach  is  wrong,  principal  among  which  is  that  the 
specification,  not  the  program,  should  define  correctness* 

Many  of  the  rules  for  software  functional  definition  resemble  Piles  given 
in  previous  sections,  and  also  resemble  design  rulCsS  to  be  given  in  the  next 
chapter  That  is  the  case,  as  T stated  earlier,  because  there  is  a conformity 
in  the  methods,  not  because  the  products  are  the  same. 

The  software  functional  definition  occupies  a part  of  the  Software 
Speeffleation  Document  (SSD),  which  I call  the  Software  Functional 
Specification  (SFS).  It  is  purely  technical  in  nature;  it  pertains  wholly  to  the 
external  characteristics  of  the  program.  For  this  reason,  many  may  choose 
to  treat  the  SFS  as  a first  (or  separate)  volume  of  the  SSD.  I have  shown  the 
SFS  as  an  iniegral  part  of  the  SSD,  inasmuch  as  it  may  be  Influenced  by  the 
internal  algorithms  in  concurrent  design  or  coding  actvities. 

Tiic  Software  Functional  Specification  responds  to,  extends,  refines,  and 
then  documents  the  technical  concepts  laid  down  in  the  SRD  and  SDD.  The 
SFS  is  not  a mere  restatement  of  the  SRD  oi  the  SDD— it  defines  the  way 
the  program  shall  respond  in  order  to  fulfill  the  requirement. 

The  SFS,  w^hen  complete  and  approved,  satisfies  the  following  criterion; 

It  defines  the  meaning  cf  program  correctness;  any  program  meeting 
the  technical  and  documentation  specifications  will  be  deemed  a 
satisfactory  deliverable. 

During  the  completion  process,  each  phase  of  the  SFS  development 
satisfies  the  following  criteria: 

a.  It  U siiflicient  yo  initiate  the  development  of  user  manuals  as  a 
separate  activity,  parallel  to  (but  coordinating  with)  any  concurrent 
program  development  activities  (design  and  production). 

b.  It  is  adequate  for  continuing  thr  program  development  acti\  ities 
(design  and  production)  with  reasonable  assurance  that  major 
revisioas  will  not  be  neces.sary. 

G.  It  is  reviewable  by  project  and  user  personnel  on  the  basis  of  its 
technical  feasibility  and  accuracy,  in  accordance  with  the  SRD,  SDD, 
and  the  other  criteria  above* 

The  rules  for  generating  the  remainder  of  the  SSD  (the  Programming 
SpecifiGaiiGn)  are  contained  in  the  next  chapter, 

11>3.1  Rules  to  Structure  Functiona;  Specifications 

Program  definition  is  primarily  concerned  with  deciding  what  the 
external  characteristics  of  a program  shall  be,  and  leaving  how  these 
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functions  are  to  be  implemented  to  the  program  design  activity^  The 
guidelines  in  this  section  aid  in  identifying  the  ftinctions  and  developing  the 
relationships  between  the  functions  and  the  data  they  process. 

1.  Complete  the  SFS  portion  of  the  SSD  as  specified  in  the  topical 
outline  supplied  in  Appendix  E,  documented  subject  to  the  rules  in 
Section  11.4. 

Segment  the  material  into  semantically  refined,  hierarchic 
levels  of  detail.  Cite  existing  material  by  reference  only  if  it 
is  a stable,  maintained  doeumentaticn.  Figure  11-5  shows  a 
graphical  outline  of  the  SFS  within  the  SSD. 

2.  Start  the  hierarchic  development  with  a one-page  block  diagram  and 
accompanying  narrative  that  shows  the  program  properly  imbedded  in  its 
environment  and  defines  the  major  system  and  data  interfaces. 

3.  State  and  display  processing  specifications  primarily  as  functional 
“black  box”  transformations  of  input  data  and  input  conditions  into  output 
data  and  output  conditions. 

4.  Display  the  distinct  program  modes,  preferably  using  data- 
transformation  descriptions  in  the  form  of  information  flow  diagrams  and 
explanatory  narrative.  State  the  logical  conditions  that  invoke  and 
terminate  each  such  mode.  Define  intricate  mode  selection  and  transition 
logic,  preferably  in  the  form  of  decision  tables  based  on  program  control 
inpvits, 

5.  Define  fimct tonal  criteria  for  the  program  in  terms  of  specifications  of 
input  data,  processing,  and  output  data,  and  by  criteria  that  define  ranges  of 
acceptable  measured  behavior  (see  Chapters  14  and  15). 

6.  Describe  input  and  output  d.ata  sets  in  terms  of  their  information 
content,  the  substnicture  imposed  by  relationships  between  items,  and  the 
correlations  among  data  items.  Leave  to  later  design  the  details  of  data 
structuring  to  accommodate  accessibility  and  storage,  unless  those 
considerations  arc  already  in  effect  (existing  data  bases),  or  are  necessary  to 
state  the  program  functional  definition. 

7.  Strive  to  structure  specifications  into  modular  forms  that  have  as  few 
connections  as  possible  with  other  speGificatioris  not  in  the  same  direct  line 
of  hierarchy.  A connection  in  this  sense  refers  to  dependencies  and 
interrelationships  between  specificatiGnis.  Well-modularized  specifications 
can  lead  to  well-modular tzed  designs.  As  aids  toward  this  end,  be  guided  by 
the  following: 


SSD 


Figure  Gfaphfcal  outline  of  the  SSD  with  functlpnal  specification  items  ^:Afnphasized 
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a.  If  tvv'Q  speGifiGafcions  correlate,  attempt  to  make  this  eonneetion  take 
the  form  of  a shared  subspecificatiori,  i^e,,  a common  definition. 

b.  If  a specification  of  a part  of  the  program’s  behavior  at  a given 
hierarchic  level  depends  on  logical  input  conditions,  then  strive  to 
partition  that  specification  into  subspecificatiDns  that  will  be 
independent  of  those  logical  conditions  at  the  next  hierarchic  level, 

.V 

c.  Avoid  specifications  iii  which  logical  control  is  to  be  specified  by  a 
subdefinition  at  a later  hier^irchic  level.  That  is,  impose  control 
definitions  downward  througli  the  specification  hierarchy,  subject  to 
(b),  above; 

d.  Strive  for  functional  /‘jpecificatiGns,  in  which  all  elements  of  each  are 

related  to  the  perfoi-mance  of  subfunetions  that  combine  to  achieve  a 
single,  nonvaryin^j  functional  goal.  When  practical,  state  subspecifi- 
cations  so  as  not  to  imply  strict  logical  sequence  of  operations  so 
much  as  subfunctional  composition  and  precedence.  ’ 

e.  Avoid  specifications,  other  things  being  equal,  who.se  elements 
modularize  unrelated  actions  together  (i.e.,  which  specify  a set  of 
subfunetions  that  do  not  have  a common  functional  goal).  A later 
alteration  to  such  a definition  could  generate  profound  side  effects  in 
other  definitions. 

8.  Extend  the  hierarchy  of  speeificatibn  detail  to  that  point  for  which  the 
set  of  filial  definition  “stubs'*  f leaves  of  the  hierarchy  tree)  contains  no 
subset  of  elements  that  could  be  useful  as  separate  or  common 
subdefinitions  of  other  definitions.  Each  such  definition  element  should 
represent  a concept  that  is  entire  and  within  comprehension. 

9.  Coordinate  functions  that  apply  to  major  information  structures  so  as 
to  isolate  dependencies  oh  internal  data-type,  record  format,  etc.,  for  each 
stnicture. 

This  v;ill  tend  to  minimize  redesign  and  recoding,  should 
the  data  representation  structure  change.  Specifically, 
define  operations  that  process  information  elements  fay 
field  identifier  or  name,  rather  than  by  position:  Describe 
operations  in  terms  of  the  field  or  fields  necessarj^  for  the 
operations  to  accomplish  their  functions. 

11,3.2  Rules  for  Enhancing  Program  Utility 

1.  Specify  the  program  so  as  to  allow  flexibility  in  tolerances  and 
formats,  and  to  adjust  criteria  for  control  decisions  without  changing  the 
L -isic  structure. 
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2.  Specify  attributes  of  the  program  in  such  a way  that  the  program  can 
nin,  at  user  option^  in  a degraded  fashion  when  input  data  quality  has 
degenerated. 

Specify  provisionsi  in  such  cases,  to  print  out  an  alarm  and 
continue,  except,  perhaps,  in  interactive  environments 
where  a stop  and  go-ahead  command  can  be  accommo- 
dated. In  any  event,  retain  the  data  and  work  up  to  the  halt 
point 

3.  Specify  program  responses  for  recognized,  expected  modes  of  failure 
so  as  to  “fail  soft”  or  “fail  safe,”  according  to  the  cost  or  risk  of  the  failure. 

4.  Orient  the  computer-to-human  interfaces  toward  tho  user  and/or 
operator. 

Such  human  engineering  can  add  much  appeal  to  the 
program,  jlist  as  an  interior  decorator  can  increase  the 
appeal  of  a home.  However,  base  such  interface  definitions 
primarily  on  requirements,  projected  perfoi'mance  gains, 
and  Implementation  costs,  and  secondarily  upon  aesthetic 
appeal. 

5.  Use  descriptive  messages  to  describe  errors  sensed  during  operations 
whenever  storage  permits. 

Avoid  messages  which  refer  to  conditions  that  violate  the 
program  s error  criteria  as  being  “illegal”  (against  the  law), 
when  what  is  meant  is  “Improper,”  “invalid,”  or  “not 
permitted”  (in  violation  of  the  program  s capability). 

6.  Specify  program  characteri sties  that  foster  testability;  in  some  cases,  a 
program  function  can  be  defined  in  terms  of  the  tests  that  validate 
correctness.  Include,  where  practical,  self-diagnostic  capabilities,  such  as 
data  checking  and  consistency  monitors,  into  the  functional  definitions. 


11.4  DOCUMENTING  TECHNICAL  REQUIREMENTS  AND 
FUNCTIONAL  SPECIFICATIONS 

Both  technical  requirements  and  functional  specifications  deal  with 
program  external  characteristics,  and,  therefore,  the  documentation  of  each 
somewhat  resembles  the  other  The  rules  in  this  section  set  forth  standards 
for  supplying  graphic  material  and  narrative  to  describe  both. 
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It  is  worth  remembering  that  the  SHD  and  SDD  are  chiefly  management- 
onented,  and  are  not  particularly  useful  as  surviving  documents,  except^ 
perhaps,  as  a means  to  record  project  histbiy.  That  is,  their  useful  lifetimes 
do  not  generally  extend  beyond  the  software  development  period. 

The  SSD  docs  survive,  and  eontains  the  complete  technical,  as-built 
description  of  the  program  produced,  The  level  of  detail  in  the  SSD  is, 
therefore,  inueh  greater  than  in  either  of  its  antecedents.  Further 
documentation  rules  for  program  specifications  are  found  in  the  next 
chapter  (Section  12,7),  and  Chapter  Ifl  has  definitions  of  standard  classes  of 
documentation.  Also  see  Section  16.3.2  for  documentor  responsibilities, 

11.d.1  Rules  for  Organizing  Documentation 

1,  Document  software  items,  such  as  requirements,  definitions,  etc., 
concurreniiy  as  those  items  are  being  developed^ 

2.  Organize  material  in  the  doeumentation  into  hierarchic  levels  of 
increasing  detail  Arrange  the  material  in  such  a way  that  the  upper  levels 
are  directly  suitable  for  ext;  action  and  presentation  at  reviews, 

3.  Display  management  and  planning  information  in  a top-down  format, 
in  which  the  top  level  summarizes  management  resource  requirements, 
project  duration,  etc.  Detail  subsequent  levels  into  eatc^ories  that  show 
increasing  levels  of  rationale  for  items  appearing  at  previous  hierarehiG 
levels. 

4,  Organize  technical  materia!  in  Dewey-decimal  ord.‘r  of  hierarchic 
definition  detail  illustrated  in  Figure  11-6.  The  numbers  for  this 
hierarchy  may  be  obtained  as  follows: 

a.  Tf  s is  the  Dewey-decimal  identifier  of  a section  in  which  an  item 
numbered  n (by  rules  in  following  sections)  appears  for  further 
detailed  expansion,  and  if  this  item  has  not  previously  appeared  in  the 
documentation  hierarchy,  then  number  the  section  detailing  this  item 
as  section  s,n  of  the  document. 

b.  Tf  an  item  number  m has  been  referred  to  as  a common  item  in 
several  places  in  the  document,  its  description  should  appear  in  some 
separate  section,  say,  section  number  d.  In  this  case,  append  any  new 
information  learned  about  the  common  item  in  section  s to  section  d 
of  the  document,  and  annotate  section  s,  item  m,  with  the  fact  that 
full  information  about  this  item  appears  in  section  d, 

G.  Start  the  top-level  Dewey-decimal  identifier  d for  .such  common  items 
with  alphanumeric  levei-1  section  number  for  ease  in  locating  and 
distinguishing  the  documentation  section  number. 
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Mode  Name 


existing 

(common) 

item 


cl  Old 't®"’ 


(s.rn) 

any  , 

;nformat'° 


d.  DenoK  the  nth  table  appearing  under  actipn  number  a using  the 
descriptor  ff.T  n, 

11.4.2  Rules  for  Representing  Functions!  Information 

each  operational  mode  (see  Figure  11-7). 
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2»  Display  major  processing  functions  within  each  niode  'primarily  as  a 
topniown  hierar^y  of  input-^proeessing-outpiit  charts  (see  Figure  11-8)  and 
accompanying  narrative,  rather  than  as  controi-logic  flowcharts,  unless  such 
charts  are  necessary  to  display  the  logieai  sequenGihg  of  program 
requirements. 


* • • 

• 9 • 


figure  11-8,  A sample  for  repre^ntlhg  hierarchic  input-processlng-output  (HlPO) 
functions  in  documentation  (two  methods  of  detailing  are  shown,  and  others  niay  also 
be  used;  cross-references  may  thus  be  necessary  between  ''cousin"  sections  of  the 

document) 
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3.  irifonnation-stream  diagrams  to  identify  the  souree  of  eaeh 
required  input,  the  required  routing  through  processes,  and  the  destination 
of  eadt  required  output 

For  example,  inputs  may  emanate  from  existing  data'^base 
filei.,  or  from  information  to  be  supplied  by  a group  of 
users  or  operators.  Outputs  may  be  destined  to  files,  or, 
perhaps,  to  users  by  mail, 

4.  Describe  inputs  and  outputs  as  {perhaps  formatted/  information 
structures,  rather  than  data  stnictures  or  storage  structures  later  to  he 
designed,  unless  these  stnictures  represent  existing  dtita  bases,  or  else  are 
relevant  to  the  satisfaction  of  a stated  software  requirement. 


5;  Document  complex  logical  multirmode  requirenients  in  the  form  of 
decision  tables.  A mode  is  defined  as  a way  of  operating  a program  to 
perform  a certain  subset  of  the  processing  requirements  that  normally  are 
associated  together  in  the  program  function. 

6.  If  internal  data  interfaces  are  required  to  define  a program  function, 
describe  the  pertinent  assumed  eharact eristics  of  the  interfaces  in 
supplementary  data  interface  definition  tables,  hierarchically  evolved.  Keep 
the  state  of  all  siich  interfaces  current,  and  make  all  references  to  data 
interfaces  during  the  definition  activity  agree  with  the  tables. 

7.  When  it  is  necessary  to  define  functions  algorithmically,  use  CRISP- 
PDL  or  some  similar  syntactic  structures  superimposed  on  (abbreviated) 
English,  mathematical  or  programming  terminoloj^  to  describe  such 
algorithms,  or  produce  flowcharts  and  narratives  along  the  guidelines  given 
in  the  next  chapter  (see  also  Chapter  17). 

8.  U.se  full  graphic  aids,  such  as  mode  diagrams,  information  (or  data) 
flow  diagrams,  data  stnicture  diagrams,  decision  tables,  timing  analyses,  and 
(only  when  sequence  is  important)  controMogic  flowcharts,  along  with 
accompanying  narrative.  Such  accompanying  narrative  should  supply 
explanatieas  and  detail  not  contained  in  the  graphic  aid  (such  as  rationale 
or  instriiGtions  on  how  to  interpret  the  graphic).  Do  not  leave  graphics 
unexplained  in  the  narrative. 

11.4*3  Rules  for  Graphic  Representations 

1.  Limit  all  graphic  representations,  such  as  mode  diagrams,  decision 
tables,  information  flow  diagrams^  data  structure  illustrations,  and  control- 
logic  flowcharts^  to  one  page  eaeh,  except  in  unusual  circiimstances.  Use 
hierarchic  expansion  and  nesting  to  provide  detail,  rather  than  off-page 
connectors. 
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Figures  11-9  and  11-10  illustrate  a hierarchic  definition  of 
program  inodes. 


1 


Rgure  11-9^  A siir^illfled  mode  diagram  for  the  MBASiO^^  interactive  language 
prdce&sar  (boxes  show  required  modes  of  operation  and  reasons  for  transitions 
between  modes  as  stated  in  the  language  specification;  this  diagram  does  not  show  the 
design  of  the  program  into  modules) 


* A trademark  of  the  Califon^ia  Institute  of  Technology: 


i 

. . ...  . \ ...A.. 
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t Primary  entry  of  cc?mm3nds  and  source  program  statements  in  normal  mode 
^all  be  from  user  interactive  terminal. 


,2  Upon  commands  LOAD  and  MERGE,  symbolic  programs  shall  be  taken  from  standard- 
format  MBASiG  or  system  files,  (See  also  requirement  for  GGPV  in  language 
specification 

.3  The  command-mode  functions  are  listed  in  Figure  1 1-9. 

4 Symbolic  files  shall  be  printed  on  line  printer  by  use  of  UOPY, , ,TO  HSP. 

.5  The  current  symbolic  program  shall  be  held  In  a form  suitable  for  EDIT, 

MODIFY,  etc. 

,6  The  current  binary  (interpretive)  code-shall. be  held  in  a form  suitable 
for  execution  upon  RUN,  60  TO,  etC; 

7 Data  Workspace  shall  hold  all  current  values  of  variables,  or  mark 
that  variables-have.  not  been  initialized, 

5 Symbolic  workspace  shall  be  written  on  a file  upon  SAVE;  symbolic 
workspace  or  other  files  written  upon  GOFY  command 

9 Fpimary  user  display  medium  shall  be  interactive  terminal* 


Figure  11-10*  A brief  mutti-mode  information  flow  diagram  and  rtarrative  that  Hsts  a fevv 
of  the  top-level  requlmments  fbr  the  command  mode  of  an  interactive  MBASIC™ 
language  processor  (later  leveis  refine  the  separate  operational  mode  requirements 
within  the  command  mode) 
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2.  Conform  symbolic  graphical  representations  of  I/O  media  and 
processing  operations  to  ANSi-X3>5-19^0  Standard  Flowcharting  symbols 
(Appendix  Ba 

3;  Draw  information-flow  lines  on  charts  as  double-line  arrows, 
preferabiy  having  both  heads  and  tails  in  the  direction  of  flow.  Draw 
eontroMogic  flow  (sequence)  lintfs  as  single  solid  lines  terminated  by  an 
arrov/^head,  only  one  arrowhead  per  line  segment.  Connect  comments  to 
charted  symbols  by  dashed  lines  without  arrowheads. 

These  Gonyentioils  are  suntmarized  Figure  11-11.  Figure 
11-12  illustrates  an  input-processing^output  deflnitiDn 
table.  Detailed  flowcharting  standards  appear  in  Seetion 
12.7.2: 

4v  Distinguish  processing  funGtions  on  hierarchically  expanded  charts  by 
horizontally  striping  the  chart  symbol.  Use  vertical  stripes  to  indicate 
process  definitions  detailed  elsewhere.  Use  horizontally  striped  symbols  to 
denote  hierarchicaHy  expanding  information  structures  within  the  current 
document.  Use  the  appropriate  ANSI  standard  symbol  (Figure  11-13). 

5*  Niunber  all  boxes,  at  the  top  right  of  each>  on  all  eharts.  Use  a pre^ 
order  traverse  of  nodes  (Section  5.1. 3.3)  for  procedural  flowcharts  and 
topological  sorting  (Section  4.3.3)  for  inform  at  ion-flowchurts.  Conform 
narrative  descriptions  to  the  chart  numbering  scheme,  such  as  illustrated. 

6.  Annolate  input  and  output  data  bases  with  appropriate  information  to 
locate  the  complete  data-ba.se  interface  dociimentatiom 

7.  Label  boxes  on  functional  diagrams  with  the  function  they  perform, 
letting  the  shape  of  the  box  define  the  agency  by  which  that  hinction  is 
accomplished. 

For  example,  raw  input  data  may  be  indicated  as  being 
recorded  on  a disk  for  latisr  backup.^  The  box,  however, 
should  not  be  labeled  merely  ‘^isk/*  but  with  its  function, 
such  as  “digital  original  data  record/' 


11.4»4  Rules  for  Nanrtirtg  and  Referencing 

L Develop  a hierarchic  table  of  contents  for  the  technical  dfeseriptiGns 
using  the  numliering  scheme  in  Rule  5 of  11.4.3,  above,  when  applicable 
(such  as  flowehails— see  Seetion  12.7.2).  Use  the  upper  left  of  each  box  in 
charts  to  refer  or  cross-reference  the  next  layer  of  detail  through  this  table 
of  contents. 
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Input  - Processing  — Output  Table 


Description: 

Mode:  Program  Mode 

Identifier;  Mode  number 

Prepared  by: 

Phone: 

Date:  Date 

Striped  If 
detailed 
further  at 
next  level 


Software 
Interfaces: 

; Interface 
’ with  other  ] 
pr.ogratns 

Program 

Modi} 

inuirfddog 

Oatu 


INPUT  DATA  SET  NAM£ 

Inputs: 

Inputs,  data  bases,  media, 
fifes,  etc. 


Program  Mode 


Processing: 


Req't.  Ref 


function  1 

SRD  s.n  1 

functioii  2 

KY2  p.r/  f 

=Xl 

f miction  n 

^ 

OUTPUT  DATA  SET  NAME  , 
Output: 

Outputs,  data  bases,  media  j 
files,  ou:. 


System/Subsystem 

interfaces 


Signmure  Date 


Figure  11-12.  Input-proceseirg-output  tfennltlon  table,  showing  fnterfaces  to  other 
program  modes  or  other  subsystems 
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Structure  type 


Expanciec!  elsewhere 
in  this  document 


Not  expanded  here,  but 
documented  elsewhere 
(reference  aUached) 


online 

storage 


name 


name 


name 


document 


name 


r}&me 


magnetic 

tape 


arbitrary 

medium 


name 


Figure  11 -1 3.  Striping  conventions  for  information,  data,  and  storage  structures 
(unstrtped  symbols  are  not  expanded  elsewhere) 
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2.  Name  all  processes  and  information  structures  used  in  later  references 
using  mnemoniGaUy  derived  symbols.  Insert  all  such  names  in  the  document 
glossary. 

Remember  that  names  given  to  required  modes  of 
Gperativin  or  to  processing  requirements  in  the  SRD  are  not 
necessarily  going  to  be  the  same  as  the  names  of  processing 
modes  or  actions  defined  in  the  SDD,  and  these  in  turn 
may  be  altogether  diflFerent  than  the  names  of  executable 
modules  and  data  structures  specified  in  the  SSD. 

3.  State  the  mnemonic  derivation  of  all  names  used  in  a description 
unless  such  names  have  previously  occurred  in  an  ancestral  definition  of  the 
hierarchy.  Names  appearing  in  *'Gousin*'  descriptions,  unreferenced  in  their 
common  ancestor,  should  be  defined  rtinemonically  in  both  cousins.  Insert 
all  mnemonic  derivations  into  the  glossary. 

114.5  ^ules  for  Decision  Table  Formats 

1.  Format  decision  tables  into  the  standard  form  used  in  Chapter  8 and 
illustrated  in  Figure  11-14.  Fill  in  these  tables  according  to  the  remaining 
rules  in  this  section. 

2.  Separate  Condition/Action  and  Stub/Entry  sections  by  double  or 
boldface  lines. 

3.  Limit  the  size  of  tables  to  one  page  using  hierarchic  subtables  if 
necessaty; 

4.  Designate  tables  by  their  mnemonic  name  and  assigned  Dewey- 
decimal  number  at  the  head  of  the  table. 

o.  Normally,  strive  to  limit  each  table  to  no  more  than  6 conditions,  15 
decision  rules,  and  15  actions  by  hierarchic  nesting  of  table  entries. 

6.  Use  dashes  to  indicate  immaterial  condition  entries  and  ignored 
actions  in  a rule.  Do  not  leave  blank  entries. 


7.  Use  a consistent  set  of  indicators  in  LEDT  condition  entries  (“Y”  or 
“N/*  or  Use  “X"  in  action  entries  to  indicate  single  actions  or 
multiple  actions  where  sequence  is  immaterial.  If  action-item  sequence  is 
material,  number  such  items  in  the  action  entry  in  their  order  of  logical 
precedence.  Assign  equal  numbers  to  processes  having  equal  precedence. 

8.  Arrange  the  action-stub  items  in  their  general  order  of  exeeiitioii^  if 
possible.  Number  each  action  item  and  indicate  whether  there  is  further 
hierarchic  development. 
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For  example,  if  there  Ls  no  further  detail,  merely  use  the 
action  number  n;  if  there  is  more,  but  the  action  is  not  one 
common  to  other  charts,  then  use  n/;  if  the  action  is  one 
common  to  other  charts,  described  by  the  cross-reference  x, 
then  write  n / x, 

9,  If  deelsion  rules  invoking  the  same  action  have  been  cornbined,  then 
state,  if  possible,  the  relative  frequencies  of  the  uncombined  rules  if  there  is 
to  be  an  attempt  at  optimizing  the  decision  logic. 

to.  Enter  only  rules  that  correspond  to  true  alternatives  into  the  table,  tf 
the  order  of  nile  testing  is  necessary  or  pertinent  to  specify  this  entiy,  then 
state  the  sequential  testing  procedure  or  give  a reference  to  the  procedure 
elsewhere  in  the  documentation. 

11.  Unless  otherwise  stated,  assume  that  control  flow  of  each  table  wi?l 
merge  into  a single  (proper)  exit  at  the  end  of  the  table. 


11.5  RULES  FOR  THE  SOFTWARE  DEVELOPMENT 
LIBRARY 


1.  Begin  with  the  full  document  outline  and  enter  an  asterisk  (*)  in  front 
of  all  sections  to  be  completed.  As  sections  are  subsequently  completed, 
remove  the  asterisk.  If  a section  expands  and  ereatss  new  subsections,  enter 
headings  for  these  into  the  Table  of  Contents  (prefixed  with  an  asterisk,  if 
not  complete). 

2.  Start  the  description  of  each  expanding  subsection  unit  on  a separate 
page.  Affix  to  each  page  a block  in  the  upper  right-hand  corner  containing 
the  date,  '‘page^of^,,”  the  subsection  mnemonic  name,  and  Dew^ey- 
decimal  number  of  the  iiniti  Date  each  page  with  its  date  of  submission 
into  the  Software  Development  Library  (SDL).  Any  changes  should  require 
redating  that  page  and  reapproval,  if  the  unit  is  in  project  change  control. 


3.  Affix  a signature  control  block  to  each  unit  to  contain  the  initials  of 
the  person  writing  it  and  the  concurring  initials  of  the  project  manager. 

These  initials  testify  that  the  documentation  specifies  the 
desired  program  behavior,  that  it  is  being  accepted  into 
project  change  control,  and  that  any  hither  considerations 
which  must  be  based  on  that  unit  can  begins 

4.  Make  the  SDL  the  central  repositoiy  for  all  documentation,  be  It 
working-level,  look-ahead,  or  approved. 
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5:  Maintain  a glossary  and  data  interface  definition  table  definitions  as 
alphabetical  files  in  the  Software  Development  Libraiy  (on  74/2  X 12-1/2 
cm  (3  X 5 in.)  or  IBM  cards,  for  exaniple,  if  not  in  computer  files),  to  allow 
for  flexibility  in  refinement  of  infprinationi 

11.6  SUMMARY 


This  chapter  has  given  a set  of  guidelines  for  developing  and 
documenting  functional  characteristiGS  of  a program^  estimating  costs  and 
schedules  for  its  production,  setting  design  eriteria,  establishing  the 
program  architecture,  providing  management  visibility  and  controls,  and 
enhancing  program  utility.  These  guidelines  become  standards  when  it  is 
necessary  to  have  a commonality  of  approach,  or  when  these  guidelines 
contribute  to  the  goals  of  the  software  project  {e,g.,  minimize  life  cycle 
costs,  maximize  income  or  utility,  reduce  cost  or  sdvedule  overruns,  etc.), 
Guidelines  in  the  next  chapter  extend  the  standardized  approach  to 
software  into  the  design  arena;  subsequent  chapters  then  cover  compatible 
standards  for  coding,  testings  and  quality  assurance. 


XIL  PROGRAM  DESIGN  AND 
SPECIFICATION  STANDARDS 


As  T said  in  Chapter  4*  there  is  probably  little  hope  of  ever  standardizing 
the  design  process  itself.  However,  much  progress  in  this  direction  can  be 
made  by  adopting  disciplines  that  encourage  the  identification  of  goals, 
problem  coastraints,  design  parameters,  and  solution  alternatives,  and  that 
coordinate  these  into  a uniform,  readable  product.  The  design  documenta- 
tion should  describe  the  program  to  the  extent  the  program  can  be 
understood  without  reference  to  the  listings. 

The  guidelines  that  follow  in  this  chapter  summarize  a set  of  standards 
and  praetices  which  encourage  design  as  an  activity  separate  from,  but 
coordinating  with,  later  coding  and  testing.  The  rules  also  integrate  the 
program  design  in  a like  manner  with  the  functional  specification  activity 
addressed  In  Chapter  11. 
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12-1  RULES  FOR  STRUCTURAL  pEStGN 


There  is  a diflFereriee  between  designing  the  struGtiire»  or  arGhiteeture,  of 
a program  and  designing  a program  in  a structured  way.  Program  structure 
refers  to  the  way  iri  which  a epmplex  algorithm  may  be  characterizei]  in 
terms  Of  suceessively  simpler  fbrms;  The  foremo^  thing  to  remember  while 
attempting  to  design  the  program  structure  is  that  it  is  the  structural 
frametvark  that  is  being  designed— not  the  procedure,  not  the  data  formats, 
n*S\^the4Qntr6l  logiG. 

The  stnieture  of  a program  primarily  manifests  itself  in  the  selection 
among  alternatives  in  variGus  design  categories,  as  described  in  Section  2,2. 
Structure  deals  with  relationships  such  as  cohesiveness  and  coupling  within 
and  among  the  program  submodules,  the  architecture  of  the  functions  and 
data  flows,  the  intended  operational  modes,  and  the  Gonceptual  information 
structures.  Structural  design  forms  the  basis  for  the  remaining  detailed 
design  effort. 


During  the  e?rly  parts  of  the  design  phase,  there  is  a strong,  almost 
irrepressible  urge,  to  begin  the  detailed  procedural  design  before  the 
program  overall  architecture  has  been  established.  Such  techniques  as 
stnictured  flowcharts  and  CRTSP-PDL  may  seem  natural  tools  for  defining 
structure,  but  let  the  designer  be  aware  that  such  tools  only  design 
procedure.  If  one  begins  a procedural  design  and  finds  difficulty  with  data 
structure  definitions,  resource  allocations,  functional  definitions,  and  the 
like,  then  probably  either  the  program  architecture  or  the  functional 
specifications  are  not  yet  sufficiently  well  understood  to  proceed  further. 
Figure  12^1  illustrates  that  processing  algorithms  are  but  one  area  among 
design  coastclorations  typically  imbedded  within  the  total  design  task.  The 
cDJi.siderations  which  interrelate  with  the  processing  design  process  demand 
that  a proper  foundation  for  such  design  be  established*  Lariy  Hawley,  a 
cplleague  at  JPL,  remarked  in  this  respect,  '“No  amount  of  riveting  can 
strengthen  a building  enough  to  make  it  a skyscraper  if  its  foundation  and 
structural  members  are  unsound/’ 

The  giiidelines  that  follow  in  this  section  reflect  software  development 
practices  which  help  to  establish  a sound  program  stnieture, 

1.  Establish  design  tradeoff  criteria  at  the  outset.  Make  tradeoff  analyses 
of  ail  potentially  useful  or  competing  methods  for  implementing  critical 
parts  of  the  design.  Don’t  throw  these  away.  Put  them  in  the  Project 
Notebooks 
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Figure  12-1.  The  Software  Design  Task  and  some  conceptual  flows  of  information 


2,  Begin  the  major  program  architecture  as  a one-page  bloek  diagram  of 
fiinctians,  such  as  Figure  12-2y  showing  major  information  flows,  data 
bases,  and  data  stniotures. 

3.  Obtain  a firm  commitment  from  cognizant  individuals  over  external 
data  bases  to  maintain  a stated  interface  stnicture,  i.e.,  format,  content,  and 
integrity-  to  inform  your  project  about  the  extent,  form,  and  schedules  of 
any  upcoming  maintenance  needed  on  the  bases;  and  to  consult  with  your 
project  before  any  subsequent  changes  to  the  committed  interface  are 
made. 


Generate  an J 
output  target 
code 


Target, 

Code  for  j 
Target  / 
Compiler J 


LIST 

Print 

indented 

source 

listing 


Includes 

CRISP  statement 
type,  nesting  level, 
and  target  labels 


I LISTING 
Cosmetized  ^ 
Listing  and  j 
Errors  / 


Figure  12-3.  Top-levbl  block  diagram  at  a conceplua)  CRISP  preprocessor,  showing 
data  floWf  rnaior  operations  and  data  structure,  inputs  and  outputs 
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4.  Analyse  functional  behavior,  data  structuring,  and  coupling  modes  of 
modiiles,  and  strive  to  maximize  module  cohesion  and  minimize  module 
coupling,  as  described  in  Section  4.4.  In  particular^  strive  to: 

a.  Define  levels  of  access  for  all  large  or  potentially  changeable  data 
structures  or  other  lesources,  to  “hide"  the  actual  data  or  resource 
behind  functions  which  access  the  data  in  the  prescribed  way.  Pass 
information  to  and  from  these  stiuctures  as  arguments. 

b,  Name  modules  using  single-verbj  single-specific-direct-object  actions 
that  truly  reflect  the  intended  function  of  the  module.  This  promotes 
functiGnal  cohesion  of  modules. 


5.  Use  top-down,  hierarchic,  modularizing,  structured  programming 
techniques  that  refine  the  program  procedural  design  into  a hierarchy  of 
detailing  decompositions  of  the  program  function  into  parts  capable  of 
being  perceived  as  a unit.  Maintain  consistency  and  concurrency  between 
data-stnicture  and  resource-access  definition  hierarchies  and  the  program 
proceduraWesign  hierarchy. 

6.  Use  informal  design  look-ahead  analyses  to  develop  architecture,  to 
study  feasibility  of  ideas,  and  to  identify  common  “basic  services"  that  can 
be  incoiiporated  as  subroutines  before  there  is  a large  investment  in  formal 
documentation  or  code.  Siibmit  approved  (signed-ofF)  design  items  into 
project  control  for  later  coding. 

7.  Describe  the  relationships  betw’een  functional  modules  and  the  data 
they  access  by  stating  how  the  Yepresentations  of  information,  manipulated 
by  functions,  are  to  be  interpreted  hy  the  “real  world." 

8.  Develop  decision  tables  for  logically  intricate  parts  of  the  program,  to 
identify  all  relevant  conditions  and  to  define  corresponding  actions. 

9.  Study  the  programming  language(s)  to  be  used  for  implementation. 
Whereas  the  upper  levels  of  design  are  encouraged  to  be  as  langua>:ie- 
independent  aj  possible,  it  is  imperative  that  the  designer  be  intimately 
acquainted  with  the  target  language  and  system  capabilities,  as  they  most 
certainty  will  impact  the  design. 


1Z2  RULES  FOR  DATA  STRUCTURING  AND 
RESOURCE  ACCESS  DESIGN 


The  fundamental  problems  in  data  structure  design  are  deciding:  (l) 
when  to  save  the  results  of  caleuiations,  rather  than  recompute  them;  (2) 
how  to  store  data  items  so  that  they  are  accessible  by  the  operations  which 
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will  transform  them  into  output;  (3)  how  to  organize  the  da^:a  so  that 
storage  and  pperatinns  are  efficient;  and  (4)  how  to  document  the  data 
stmcture  so  that  others  can  understand  the  operations  performed  on  it. 
Such  discussions  are  influenced  by  data  type,  amount  of  data*  relationships 
among  data  elements*  and  the  algorithms  that  operate  on  the  structures. 

The  guidelines  that  follow  primarily  address  the  design  procedures  for 
structuring  data;  however*  most  of  these  apply  equally  to  designing  acGesses 
to  other  resources,  as  well.  I would  like  the  reader  to  know  that  1 intend 
that  the  same  niles  be  applied  in  the  more  general  case. 


1.  Start  with  the  most  abstract  concept  of  the  information  structure  of  a 
problem.  Then  use  stepwise  refinements  to  create  a hierarchy  of  more  and 
more  detail.  At  each  step,  refine  the  representation  of  data  items  or  the 
operations  on  data  items  in  a way  which  details*  but  does  not  conflict  with, 
the  previous  levels  of  refinement 


Figiire  12^3  depicts  a top-level  architeetural  tier-structure 
chart  for  a conceptual  CRISP  preprocessor.  The  indicated 
modules,  data  flows,  and  data  structures  show  the 
designer's  first  concerns  and  decisions;  later  refinements 
delve  into  secondary  details. 

2,  Concentrate  primarily,  at  each  level,  with  is  being  done,  rcther 
than  how  it  is  to  be  dbne  (which  will  be  defined  at  later  levels}.  It  is  proper 
to  use  a look-ahead  design  to  cheek  feasibility  of  the  eurreht  level  of 
thinking;  however,  submit  only  approved  (signed^ofF)  design  items  into 
project  control  and  later  coding. 

A typical  abstraction  of  a list  structure  for  the  PARSE 
module  in  a CRISP  preprocessor  might  appear  as  depicted 
in  Figures  12-4  and  12-5.  ! 

3,  At  each  level  of  abstraction,  attempt  to  discover  only  the  relevant 
aspects  of  the  information  structures  of  the  probleni,  such  as: 

a.  Amount  and  source  of  each  information  stream. 

b.  Types  and  other  attributes  of  data  elements,  e,g,,  units. 

c.  Relationships  among  data  elements. 

d.  Composition  of  data  constituents  from  data  elements. 

e.  Operations  to  he  performed  on  the  information. 

f.  Frequency  of  access  and  response  time. 

Then  invent  conceptual  data  structures  or  refinements  of  previously  defined 
structures  which  can  accommodate  (a)  through  (d),  above.  Invent 
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Rgure  12-3.  An  arcttitecturat  tier  design  chart  for  a simple  CRISP  preprocessor  (note 
that  some  flows  are  Indicated  but  not  annotated  with  specific  type  or  label  infdnnatEjn; 
other  flowS}  such  as  communication  with  ERROR,  have  been  omitted  attogether,  until  a 

later  abstraction) 
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F 


V P 


F = flag  field 
V - value  field 
P = pointer  field 


\b)  Sequence:  If  character  at  GHARPTR  in  BUFFER  matches  character 

in  V-field  of  current  token,  next  tokt*n  is  theqne  juSit 
below  current  token,  if  there  is  no  match,  next 
token  [s  found  by  following  P field: 


next  token  If  no  match,  do  not  advance 
CHARPTR  (null  V never  matches} 


next  token  if  match, 
advance  CHARPTR 


fc)  Flag-Field  Directives: 


n 

n 

L_J 

i 

SIB 

□ 

Set  next  parameter  token;  V^field  0,  P-field  CHARPTR. 
Set  parenthesis  counter  PAR  ENS  - 1 ► 


Increment  V -field  of  parameter  token>  Advance  CHARPTR, 
and  advance  to  next  token. 


Increment  PARENS  by  1 and  increrr.ent  V field  of  parameter 
token  by  1 if  there  is  a match.  Advance  to  next  tokens 


If  there  is  a match,  advance  CHARPTR  and  decrement 
PARENS  by  t.  Then,  if  PARENS  = 0,  advance  o token  beJovv. 
If  PA  RENS>0,  increment  V-fieid  of  parameter  token, 
advance  to  token  in  P-fleld,  and  advance  CHARPTR.  If 
no  match,,  follow  (b),  above; 


(til  Parameter  Tokens;  Contains  length  L and  pointer  to  first  character 
in  the  inpiJt  buffer  tor  each  paramete.  string  of 
CRISP  statement: 


Figure  12-4,  Design  preliminaries  for  list  tokens  and  conventions  for  list  parsing  of 

CRISP  statements 
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conoeptual  operations  e:  these  structures  to  aGcommodate  (e).  Assess  the 
correctness  of  the  representation^  that  is,  convince  yourself  that  operations 
on  the  data  structures  correspond  to  intended  operations  on  the  information 
Structures  (i  ci,  the  real  world). 

4.  isolate  data  structures  having  the  same  operations  and  type  attributes 
into  a level  of  aecess  Make  each  level  of:  access  have  a set  of  data  resources 
which  it  owns  exclusively,  and  within  which  only  subordinate  levels  of 
access  are  permitted  to  access  differently  (see  Figiire  12-6); 

5;  Envision  data  items  and  the  relationships  among  items  as  a *^data 
graph”  stnicture.  Strive  to  keep  such  structures  simple  enough  so  that  a 
two-dimensional  one-page  display  of  the  data  format  with  interconnections 
and  indicators  of  subgraphs  can  be  drawn  to  document  the  design  of  that 
stnicture.  Whenever  a data  graph  has  more  than  one  disjoint  connected 
subgraph,  consider  whether  the  disjoint  components  might  not  be  better 
defined  as  separate  structures. 

Note  that  table-driven  algorithms  simulating  finite  state 
machines  are  actually  interpretersi  in  which  the  “program” 
is  the  tabular  data  structure.  Selection  of  the  next  state  is 


figure  12-6.  Organization  of  program  modules  into  a level  of  access  composed  of  a set 
df  f unctions  that  own  a data  structure 
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analogous  to  IF  or  CASE,  and  cycles  in  the  data  grapli  are 
loops  in  the  “program/'  The  data  graph,  in  fiiLjt,  is  the 
“program”  flowchart.  Tf  this  flowchart  is  unitnictured, 
then  that  data  structure  suffers  from  the  same  faitits  as  an 
ordinary  unstraetured  program^  The  list  displayed  in  Figure 
12-5  is  highly  organized,  but  a few  nnstnictured  jumps  out 
of  loops  exist,  for  example.  The  designer  n>ust  assess 
whether  the  reasons  for  this  lack  of  structure  are  justified 
with  respect  to  the  set  of  competing  eharaeteristiGS 
(Section  4*5). 

6*  Decide  upon  the  degree  of  data  packing  to  save  space,  as  opposed  to 
the  lack  of  packing  to  save  access  time*  If  packing  saves  time  as  well  as 
storage,  consider  whether  rhe  program  will  be  more  complicated  or  require 
additional  expense  {e.g.,  garbage  collection)* 

7.  Cany  through  look-ahead  design  efforts  for  each  critical  item  all  the 
way  down  to  that  level  of  detail  requii'ed  to  ascertain  storage,  access  time, 
and  other  considerations  which  could  seriously  affect  the  remainder  of  the 
data  structuring.  Perform  such  feasibilil^’  studies  early  enough  so  that  the 
impact  of  any  adverse  findings  can  be  accommodated* 

8*  For  operations  that  act  on  data  structures,  specify  Operands  by  field 
name,  rather  than  by  an  assumed  substructure  position.  In  this  way, 
algorithms  become  insensitive  to  the  substrueturing  of  the  data. 


12.3  RULES  FOR  DEVELOPING  STRUCTURED 
PROGRAMS 

This  section  contains  guidelines  that  relate  to  the  formalized  develop- 
ment of  the  detailed  program  procedure  as  a hierarchy  of  structured 
modules  implemented  from  the  top  down,  In  principle,  the  coding  can  take 
place  concurrently,  also  from  the  top  down  in  execution  sequence,  after  the 
architectiiral  phase,  as  design  items  are  completed: 

The  program  architectural  design  phase  may  be  considered  to  be  ended 
when: 

a.  All  major  levels  of  access  have  been  identified,  resources  allocated, 
and  the  aGcess-lev  el-hierarchy  established. 

b;  The  preliminary  functional  analysis  and  program  structural  definition 
exist  and  are  documented  in  accordance  with  SDB  standards. 
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G.  The  level  of  detail  extends  only  down  to  the  point  reqviired  to  fix  cost 
and  schedule^  within  acGeptabje  variances  {say»  a 10%  {{oal). 

The  following  rules  outline  the  kinds  of  steps  necessary  to  formulate  and 
structure  the  program  procedure  in  a disciplined  way. 

1.  Define  phase  one  of  the  program  design  as  that  amount  of  work  whieh 
will  be  required  to  satisfy  the  architecture,  or  '‘design  definition'" 
requirements.  This  is  a look-^ahead  effort  prior  to  begianing  the  forma! 
design-Gode-test  cycle  with  concurrent  documentation. 

2.  Do  not  begin  the  formal  procedural  design  (the  SSD)  until  the  amount 
of  work  has  at  least  reached  that  preliminary  level  which  satisfies  (a) 
through  (g),  above.  Then  begin  the  formal  task  of  developing,  doeumenting, 
and  demonstrating  this  design  nnetu  at  level  one  for  the  5SD. 

3.  Begin  the  main  program*  each  common  subroutine,  and,  perhaps,  some 
of  the  jnajv>r  subprograms  at  documentation  level  one. 

4.  Monitor  the  program  structural  development  using  a WBS  and  tier 
chart,  or  equivalent  Each  tier  consists  of  all  program  modules  that  possess 
the  sSame  degree  of  hierarchic  nesting  in  relation  to  the  level-one  main 
ptogram. 

Note  that,  in  a program  without  subroutines  or  level-one 
subprograms,  the  tier  number  is  the  same  as  the 
documentation  level  number.  The  organization  into  tiers  is 
illustrated  in  Figure  12-7^ 

5.  Define  phases  of  development  subsequent  to  the  preliminary  (or 
architectural  design)  phase  so  as  to  agree  with  aay  given  priorities  or 
Gapabilities  set  forth  in  the  Software  Functional  Requirements  or  in  the 
Software  Development  Plan,  Such  phases  ate  to  be  defined  by  sets  of 
modules  next  in  top-down  order  on  subtrees  of  the  tier  chart  (see  Figure  12- 
8).  The  sets  of  modules  for  a phase  are  to  he  chosen  as  testable  milestones 
that  increase  project  productivity  by  demonstrating  (using  dummy  stubs) 
the  appropriate  partial  correctness  of  the  program  in  responding  to  a stated 
functional  requirement 

6.  Orient  the  design  process  so  as  to  complete  an  entire  defined  phase  as 
a major  project  milestone.  Complete  and  document  all  modules  at  the 
current  formal  design  phase  before  proceeding  to  the  next  format  pliase, 
(This  rule  does  not  pertain  to  informal  look-ahead  efforts.) 
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1.2*3 


Figure  12-7.  Organization  of  program  modules  into  tiers  by  nesting  hierarchy  (level 
number  refers  to  documentation  hierarchy:  tier  number  re^rs  to  degree  of  nesting 

within  main  program) 


7.  Direct  the  effort  within  defined  projeet  phases  toward  completion  of 
Tnoduios  having  the  lowest-numbered  tier.  That  is,  proceed  from  the  top 
downward  within  each  work  phase. 

When  deemed  necessaiy  (iby  project:  management),  segment  program 
development  among  several  programmers.  Such  segmentation  shall  only 
oeeur  at  striped-module  interfaces,  and  each  programmer  must  be  able  to 
view  the  requirements  placed  by  previous  program  levels  on  that  striped 
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Phase  1 Phase  2 Phase  3 


Figure  12-8.  Formal  design  phases  conceptually  Illustrated  on  the  (H'ograni  tier  graph  as 
partitions  of  the  graph  that  encompass  more  and  more  modules  of  the  program 
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Sec.  12.4]  Applying  Structured  Frogramtning  Theory 

module  as  a total  interface  specifieation.  If  timing— either  epoch  or 
duration— is  a commodity  visible  to  other  modules,  it  is  to  be  included  as 
part  of  the  interface  definition, 


12.4  RULES  FOR  APPLYING  STRUCTURED 
PROGRAMMING  THEORY 

Structured  programming  is  not  programming  to  eliminate 
although,  in  some  languages^  structured  programs  are  “gG^to'*-free»  Such  is 
the  case,  for  example,  using  CRISP.  Rather,  structured  programming  is 
GGneeiving  a program  in  such  a way  that  the  need  to  think  about  having  to 
“gp-to**  hardly  ever  arises.  It  is  programming  with  logical  stnietiires  that 
encourage  clear  thinking. 

If  a language  possessed  only  the  minimal  canonical  set  of  structures 
(sequence,  WHILEDO,  TPl’HENELSE),  one  can  argue  that  there  are 
certainiy  times  when  control  branches  are  needed.  If  the  coding  language  is 
intended  to  be  assembly  language,  this  argument  is  even  more  intense.  To 
maintain  the  aims  of  structure^  I have,  therefore,  expanded  the  list  of 
recommended  structures,  in  flowcharting,  as  well  as  in  their  eorresponding 
CRISP  forms.  Ik>th  flowcharts  and  CRISP  '.solate  the  designer  from  “go-to” 
thinking. 

This  section  contains  guidelines  for  generating  the  structured  control 
logic  hierarchy  of  the  program.  The  development  of  this  hierarchy  takes 
place  ih-step  with  the  development  of  the  data  structure  and  resource 
access  hierarchies  described  in  Section  12.2  (see  Rule  5 of  Section  L2.l). 

1,  Arrange  functional  blocks  naturally  in  a hierarchical  design  using  only 
the  control  structures  equivalent  to  those  described  in  Appendix  G.  Each 
block  has  one  entry  point  and  one  normal  exit. 

2.  Use  recursive  aiibroiitines  (i.e.,  routines  that  call  themselves  or  each 
other)  only  when  a comprehensive  statement  can  be  made  to  assure  that  the 
required  functional  behavior  is  achieved.  Every  horizontally  striped  module 
in  a stmetured  design  must  be  formally  replaceable  by  its  flowchart  or 


3.  In  cases  where  alternative  control  structures  perform  identical 
functions,  choose  that  which  best  satisfies  the  given  ordered  set  of 
competing  characteristics. 

For  example,  when  execution  time  outranks  memorj' 
allocation  considerations,  one  naturally  minimizes  memory 
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requirements  arid  exeGution  time  whenever  possible.  One 
considers  structures  that  reduce  memory  requirements  but 
increase  execution  time  only  when  (a)  the  loss  in  speed  is  a 
negligible  fraction  of  the  exeGution  time  of  that  module 
and  the  reduced  core  is  a significant  portion  of  storage  for 
that  module,  (b)  the  module  operates  in  an  infrequently 
ealled,  low-speed  program  branch  in  which  the  increased 
time  is  a negligible  fraction  of  the  branch  execution  time, 
or  (e)  the  extra  branching  GOntributes  to  modularity  and 
readabii  ?ly  at  a modest  loss  in  speed  or  storage, 

4.  Whenever  possible,  design  the  program  control  logic  and  functions  to 
favor  high-speed^  normal  operation';  if  additional  functions  are  required  in 
order  to  achieve  a structured  design,  place  them  in  the  slpwer^speed,  less 
frequently  used  branch. 

Tn  some  casesj  the  requirement  for  structure  may  be 
relaxed  by  the  project  management  oii  a case-by-ease  basis, 
as,  for  example,  in  high-speed  loops  where  the  time  to  set, 
test,  and  reset  ijtruGture  flags  would  be  a significant 
fraction  of  the  loop  timings  In  such  eases,  however,  the 
benefit  and  correctness  must  be  clean 

5.  Use  a structure  flag  to  record  the  outcome  of  a decision: 

a.  When  the  decision  result  must  be  available  later  in  the  program  but 
the  data-spaee  upon  which  the  decision  was  based  will  be  changed  by 
then,  so  that  the  subsequent  decision  cannot  be  made  correctly,  or 

b.  When  the  decision  must  be  available  later  in  the  program  and  the 
flag-set  and  flag-test  storage  and/or  time  is  less  than  that  required  to 
test  the  condition  again, 

6.  When  a structure  flag  is  to  be  used  in  a loop  to  record  the  outcome  of 
the  loop-termination  condition  for  later  use,  in  compliance  with  Rule  5. 
above,  preset  the  flag  to  indicate  “unfinished''  prior  to  loop  entry,  and  then 
set  it  to  indicate  “finished' ' under  tbe  appropriate  condition. 

The  flag  test  may  be  located  either  at  the  beginning  or  at 
the  end  of  the  loop,  as  illustrated  in  Figure  12-9*  Other 
things  being  equal,  placement  of  the  flag  test  at  the  loop 
beginning  increases  top-down  readability. 

7.  Consider  using  a stack  stnieture  to  save  loop-structure  flags,  as 
iilustrated  in  Figure  12-10,  below,  imless  the  staekHinstack  operation  is  a 
nomnegligible  fraction  of  the  module  execution  time. 
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This  proc^ure  is  hot  only  a Gonyenienct,  since  one  need 
not  keep  track  of  all  the  loop  flag  names,  but  also 
somewhat  of  a savings  in  mervioty  locations  because 
separate  flags  are  not  needed  for  eacli  loop.  One  loop  flag 
stack  suffices  for  the  entire  program.  The  value  of  the  stack 
pointer  is  the  level  of  loop  nesting  at  any  point  in  the 
program, 

8.  Do  not  use  stnictiire  flags  to  force  abnormal  terminations  to  the  same 
point  as  normal  terminations.  Abnormal  terminations  are  defined  as  those 
in  response  to  fatal  errors  which  require  that  control  be  diverted  to  a 
program  recovery  mode,  si»ch  as  return  to  the  user  for  subsequent  decision 
making  and  manual  operations.  In  cases  where  a recovery  procedure 
partially  or  totally  lies  within  the  program,  take  steps  to  assure  that  the 
recovery  procedure  accommodates  every  state  of  the  program  from  which 
the  abnormal  transfer  occurs. 

9i  Avoid  duplicate-code  function  blocks  wherever  possible,  using 
subroutines  or  structure  flags,  as  needed^  except  when: 

a.  The  functipn  can  be  coded  in  fewer  statements  than  needed  for  the 
setting  and  testing  of  structure  flags,  or  than  required  in  the 
subroutine  calling  sequence. 

b.  The  structure  flag  test  time  or  subroutine  linkage  time  is  a non- 
negligible  part  of  the  module  execution  time. 

For  example,  the  two  flowcharts  shown  in  Figure  12-Xl  have  the 
^ame  program  function;  flowchart  A has  the  function  / shown 
twice  (duplicated  code),  whereas  flowchart  B has  renioved  the 
duplicate  code  by  introduction  of  a structure  flag. 

16.  Limit  paranormal  exits  from  canoniG  stnictures  to  situations  that  are 
either  pathological,  abortive,  absolutely  necessary,  or  oulside  the  normal 
function  of  the  stnicture. 


12.5  RULES  FOR  REAL-TIME  STRUCTURED 
PROGRAMS 


The  program  stnictures  for  non-reabtime  programming  form  the  basis 
for  the  separate,  modular  sequential  segments  of  real-time  programs; 
however,  the  added  element  of  time  interaction  makes  reaUtime  program 
design  a more  error-prone  activity,  and  even  testing  is  inherently  a more 
difficult  and  lengthy  process.  The  rules  that  follow  in  this  section  are 
guidelines  whidi  reduce  the  mental  capacity  needed  to  comprehend  and 


Figure  12-11.  Two  realisations  of  a looping  function;  (a)  using  a dupflcated  function 
(b)  using  a structure  flag  and  no  duplication 


design  such  programs.  They  also  promote  original  eorreetness  and  make 
verification  testing  a more  practical  and  certain  activity. 

1;  Avoid  the  use  of  interacting  concurrent  processes  as  a means  of 
solving  a programming  problem  unless  it  is  neGessary;  os  fixed  by 
environmental  requirements,  or  else  unless  there  is  a clear,  identifiable 
advantage  which  outweighs  the  extra  costs  that  will  be  incurred  to  achieve 
reliability. 
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2.  Design  concurrent  or  real-time,  interi^pt-driven  modules  using  only 
hierarchic  nestings  of  the  structured  forms  given  in  Appendix  G. 
ConeuiTent  processes  eventually  merge  upon  normal  termination  of  each* 
and  proceed  only  when  all  component  siiburocesses  have  terminated 
normally, 

3*  Identify  or  define  the  level  of  access  in  the  system  nucleus  that  will 
permit  processes  to  communicate,  synchronize,  and  allocate  shared 
resources  on  a mutually  exclusive  basis.  If  these  are  not  provided  by  the 
supplied  operating  system,  devise  methods  to  implement  these  either  into 
the  operating  system  or  into  the  program  being  developed. 

4.  Orient  program  designs  toward  developing  consistent  programs  only 
{see  Section  6,2).  Assess  consistency  as  well  os  program  correctness  during 
the  design  process. 

.5.  Strive  to  design  processes  in  terms  of  fufictions  that  can  be  easily 
tested  on  a practical  real-time  basis. 

6.  Define  synchronization  and  communication  requirements  for  processes 
consistent  with  Section  6,2.4. 

7.  State  a policy  or  design  niie  for  each  set  of  shared  iesoufces  that  will 
make  the  corresponding  processes  deadlock-free.  Prove  that  each  such 
policy  is  sufficient  to  prevent  deadlocks. 

8.  Set  interrupt  priorities  for  hard-real-time  processes  to  assure  that 
process  deadlines  are  not  missed.  Use  look-ahead  feasibility  .studies  to 
estimate  the  likelihood  of  timing  errors  in  criticalnieadline  modules,  hut 
maintain  the  top-down  formal  development  discipline. 

9.  Arrange,  where  possible,  to  monitor  deadline  status  and  to  flag  timing 
errors.  Strive  to  design  the  program  ro  that  the  program  degrades 
gracefully,  but  does  not  faii,  when  deadlines  are  missed. 

Design  for  the  worst  case.  In  some  eases,  the  allGcation  of 
more  hardware  (e.g,,  CPUs)  to  a particular  set  of 
concurrent  tasks  is  possible,  and  is  often  more  cost  effective 
than  ttying  to  fit  too  many  things  into  a single  restricted  set 
of  hardware. 

10.  Identify  to  what  extent  resGiircc  protection  (Section  6.2.3)  is  needed 
in  the  program  being  developed  and  to  what  extent  the  operating  system 
hilfills  these  needs.  Accommodate,  to  the  greatest  extent  possible,  those 
needs  not  provided  by  the  operating  system  by  setting  appropriate 
programming  standards. 
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11,  Do  not  attempt  to  gain  arbitration  of  interrupt  processes  by 
reassignment  of  priorities  (or  interrupt  disabling)  except  in  cases  where 
time  is  at  a premium  and  thcfre  is  a reasonable  assurance  that  the  program 
integrity  (or  consistency)  will  not  be  violated.  Similarly,  do  not  relax  the 
requirement  for  corisistency  unless  it  can  be  shown  that  any  inconsistency  is 
momentary,  and  performance  lies  within  requited  limits, 

12.  Identify  interacting  resources  and  synchronizaiion  requirements 
among  mutual  resources  early  in  the  top^bwn  development  of  the  program 
design,  preferably  at  the  same  level  that  displays  Ihe  program  fork  (Figure 
12^12). 
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Figure  12*12.  Identif teuton  and  documentation  of  interacting  resources  and  synchroni* 
zation  requlremehts  at  first  (evet  in  tpp*down  development  where  processes  fork  into 

concurrent  activities 
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12.6  STANDARD  DESIGN  PRACTICES 


This  section  rionlains  a few  general  rules  for  developing  specifications 
that  relate  to  the  program  quality,  as  reflected  in  its  reliability, 
maintainability,  generality^  usability,  modi  flab  ility,  and  performance, 

1.  Use  standard,  already  proved  {and  documented),  structured  algorithms 
and  code  whenever  possible. 

2.  Minimize  the  functions  in  each  branch  following  a decision  node  by 
locating  above  the  decision  node  all  functions  which  logically  precede  or 
operate  on  data  sets  that  are  independent  of  the  branching  condition,  The 
first  function  in  each  branch  is  thus  dependent  on  the  branching  having 
been  executed.  Locate  below  the  corresponding  collecting  node  all 
subsequent  functions  that  are  independent  of  the  branching. 

3.  Do  not  use  identical  (or  equivalent)  test  conditions  in  succeeding 
branching  nodes  if  the  data  on  which  the  decision  is  made  has  not  changed; 
this  is  an  indication  of  unnatural,  artificial  stmeture. 

4.  Provide  programming  standards  to  prevent  the  inadvertent  misuse  of 
common  resources,  such  as  variable,  label,  and  file  names,  storage 
occupancy,  I/O  and  interrupt  facilities,  etc.,  when  not  provided  by  the 
programming  system, 

5.  Design  programs  or  subprograms  defined  by  decision  tables  to  provide 
complete  testing  of  the  ELSE-rule,  unless  (l)  an  ELSE-event  is  impossible, 
or  (2)  the  consequences  of  not  testing  the  ELSE-event  are  identifiable  and 
justifiable  on  a case-by-case  basis. 

6.  Specify  or  build  flexibility  into  the  program  to  allow  changes  in 
tolerance.s,  formats,  and  to  adjust  criteria  for  control  decisions  without 
changing  the  basic  structure  of  the  program. 

Designing  for  flexibility  does  not  mean  designing  for 
generality;  generality  tends  to  weaken  module  cohesive- 
ness,  whereas  flexibility  does  not.  However,  when  a general 
app-oach  is  as  easy  to  implement  as  a specific  one  and 
exhibits  the  same  cohesive  class,  design  for  the  general 
case. 

7.  Provide  options  in  nmning  the  program  to  accommodate  fallback 
methods  for  severe  conditions.  However,  avoid  options  that  may  overly 
complicate  or  seriously  degrade  performance.  Specify  a no-stop,  no-abort 
mode  f r programs  processing  data,  so  that  the  program  need  not  stop 
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because  data  quality  has  degenerated.  If  a stop  capabiltly  is  programmed; 
make  provisioas  to  retain  the  data  and  work  up  to  that  point.  Provide  a 
means  for  continuing  the  program  at  the  next  step,  unless  to  do  so  is  not 
meaningful. 

8.  Design  the  program  to  have  default  values  for  control  options  so  that 
the  program  can  he  run  in  its  normal  mode  without  the  ne^  for  control 
inputs. 

9.  Check  for  errors  in  data  passed  befeveen  major  modules  (especially  if 
separately  compiled  or  designed  hy  dijfferent  individuals).  Include  self- 
checking  arid  monitbring  features  within  critical  modules. 

IG.  Strive  to  design  the  control  logic  of  a module  so  as  to  be  independent 
of  the  way  data  is  stored,  and  modularize  accesses  to  data  structures  so 
that,  if  data  is  restniGtiired  at  a later  time  (e.g,,  for  more  effieieney),  only 
the  access  modules  need  to  be  altered. 

12.7  RULES  FOR  DOCUMENTING  STRUCTURED 
SPECIFICATIONS 

Dbeumentation  of  the  procedural  and  data  design  becomes  the 
programming  specification,  and,  onee  this  ha.s  been  coded,  checked,  -vid 
delivered,  it  becomes  the  built”'  specification.  The  design  process  thus 
culminates  in  a body  of  information  contained  in  the  Programming 
SpeeifiGation  portion  of  the  SSD. 

The  extent  to  which  the  SSD  gets  filled  in  and  the  order  in  which  the 
filling  gets  done  is  set  by  project  management  in  phases  as  described  in 
Section  12.3  and  Chapter  10^  Having  a comprehensive  SSD  outline,  such  as 
that  in  Appendix  E,  even  if  it  is  not  going  to  be  filled  in  completely^  can  be 
a tremendous  boon  in  the  design;  because  the  designer  can  use  it  &s  a 
mental  jog,  filling  in  each  item  in  his  own  mindi  deciding  how  things  should 
be  done.  If  he  cannot  respond  to  each  item,  even  in  hts  own  mind,  thern  he 
is  probably  going  to  have  trouble  somewhere  along  the  way.  graphical 
sketch  of  an  SSD  with  emphasis  on  the  Programming  Specification  appears 
in  Figure  12-13  (Figure  llro  contains  a graphical  outline  of  the  SFS 
portion  of  the  SSD). 

T will  assume  here  that  a com plete  program  internal  specification  consists 
of  a combination  of  flowcharts  (or  equivalenty,  narrative  descriptions,  data- 
.structure  definition  tables,  Correctness  assessments,  etc.,  and  T give 
doeumentation  rules  for  each.  The  fevel  of  detail  described  here  will  later 
be  labeled  as  ”Class  A”  documentaticn  in  Chapter  16.  The  actual  amount 
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and  lype  of  documenta tion  for  any  given  project,  however,  may  be  more  or 
less  than  what  I specify  in  the  reinainder  of  this  secfion.  Guidelines  for 
deBning  a full  range  of  levels  of  documentation  appear  in  Chapter  16. 

12^7.1  Gieneral  Rules  for  Oocumeittation 

In  the  guidelines  that  follow,  the  term  “inodule'Vrefers  to  a flowchart  {or 
equivalent)  and  its  accompanying  narrative;  The  flowchart  displays  the 
control  logic  and  operations  making  up  the  aigptithin  and  the  narrative 
extends,  explains,  and  expands  upon  the  procedural  materi<ai  When 
feasible,  these  may  be  arranged  as  illustrated  in  Figure  12-14  for 
readabili^. 

The  overall  guideline  that  has  governed  the  development  of  these 
documentation  rules  is  the  following  (for  ‘‘Glass  A”  detail): 

Documentation  of  each  module  should  exist  to  a sufficient 
degree  that  correofness  can  be  assessed  for  each  individual 
module,  formally  on  the  basis  of  its  controldo^e,  and  by 
audit  for  its  functional  completeness,  Speciflcation  of  data 
structure  detail  and  formats  internal  to  a module,  as  well  as 
requirements  relative  to  accumulated  numerical  and  timing 
errors,  may  be  deferred  to  a later  level  of  the  documenta^ 
tion,  if  appropriate. 

This  section  also  contains  guidelines  to  hasten  the  dOGumentation 
process. 


Figure  12-14.  Insertion  of  flowchart  in  the  SSD  as  a foldout  on  the  last  niarrative  page 
desciibing  the  flowchart  can  enhance  readability  when  only  one  side  of  the  page  is 

used 
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Iv  Make  design  doGumehtaition  fo^  the  ihteiface  between  design  and 
coding  acitivities;  however,  do  not  get  in  series  with  the  cleriGal  activity  of 
doing  the  forjiial  dooumentatioh, 

It  is  permissible  to  code  from  approved  hand-written 
specifiGations  while  the  documentation  is  being  ^ed  or 
drafted^  for  example  (see  the  method  illustrated  in  Figure 
10-7). 

If  working  documentation  can  be  entered  and  maintained  in  computer 
files,  rather  than  produced  by  hand,  then  by  ail  means  do  so,  in  order  to 
minimize  documentation  lag  and  to  promote  project  design  visibility 

3.  Strive  for  clarity.  Remember  that  doGumentation  is  for  communicating 
ideas  to  people.  Tlierefore,  specifications  should  discuss  the  program  in 
terms  comir  on  to  the  developer,  coder,  later  maintenance  personnel,  and, 
perhaps^  the  user  as  well.  Even  formaib  unambiguous  language  specifiGa- 
tions  may  very  often  require  natural  language  explanations,  graphical  aids^ 
and  exiunpies  for  understanding. 

4 Strive  for  completeness  without  redundancy.  Reading  a design  should 
not  require  a translator,  nor  learning  a large  data  base,  nor  consultation  of 
the  listings. 

Si  Specify  controMogic  for  a given  module  fiompletely,  so  that  module 
control  can  be  assessed  for  correctness,  or  coded  and  tested,  with  no  other 
aid  than  references  to  preceding  levels  of  the  procediiral  design  and  to 
material  in  the  non-procedural  sections  of  the  Software  Specification 
Document  at  the  current  development  phase, 

a.  Ail  decisions  are  to  be  expliGit  and  determinable  within  each 
individual  module*  there  should  be  ho  need  to  refer  to  deeper  levels 
of  design  or  code  (see  Figure  12-15), 

b,  Unslriped  modules  must  have  explicit  values,  conditions,  and  reasons 
stated  for  ail  control  flag  assignments. 

G,  For  striped  submodules  that  alter  one  or  more  control  flags  for  the 
current  module  or  a parent  module,  state  the  explicit  values, 
conditions,  and  reasons  for  all  control  flags  altered. 

6,  Document  the  functional  characfemtics  of  a module  to  that  point 
which  permits  an  audit  of  the  algorithm  of  the  current  module  against  its 
stated  function  and  an  assessment  of  functional  correctness.  Specifically, 

a.  Uristriped  modules  are  to  be  described  explicitly  enough  to  permit 
coding  without  functional  ambiguity  and  without  reference  to  deeper 
levels  of  design  or  previously  completed  code. 
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Figure  12-15.  Making  a module  complete  enough  tor  control  logic  proof  of  corroctnees 
and  immediate  codabiUty  (cro33^-out  boxes  are  to  be  replaced  by  those  connected  by 

dashed  lines) 
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b-  Interfaces  of  external  subprograms  that  are  not  part  of  the  current 
dfesign  (vertieally  striped  modules)  are  to  be  described  explicitly*  in 
sufficient  detail  that  any  subprogram  satisfying  the  stated  interface 
charaGteristics  will  operate  correctly  iii  the  current  design.  Beferences 
to  documents  that  provide  additional  information  may  be  included 
but  explicit  interface  charaeteristiGs  must  always  be  described  iii  the 
SSD. 

G.  Striped  symbols  of  the  current  module  that  receive  control  flags  from 
the  current  and/or  parent  modules  must  have  accompanying 
narrative  explaining  alt  conditions,  values  and  actions  for  each  setting 
of  the  flags; 

d.  Functional  descriptions  of  striped  symbols  may  be  quite  broad,  but 
must  be  complete,  and  tell  what  actions  that  submodule  p^erforms. 
No  function  may  appear  in  a module  at  level  n -h  1 that  is  not  a 
component  functi on  of  that  module  as  described  at  level  n. 

e.  Module  fiinetions  should  be  described  using  assertions  defining  the 
computer  state  upon  entiy*  the  specific  action  that  takes  place,  and 
the  relevant  state  of  the  computer  on  exit^  including  tin^e  Or  sequence 
dependencies,  quantitative  measures,  and  interrelations  among 
interfaces. 

7.  Declare  d/i/a  structures  accessed  by  unstriped  submodules  as  to 
specific  type  attributes  necessary  for  coding  in  the  intended  programming 
language  at  the  current  flowchart  level  without  ambiguity.  Definitions  of 
internal  data  structures  accessed  by  striped  modules,  not  pertinent  to 
control  logic  or  functional  Gorrectness,  as  specified  in  Rules  5 and  6,  above, 
may  be  refined  in  later  levels  in  the  design.  These  sTjccessiveJy  provide 
more  and  more  detail  about  the  data  structures  and  requirements  involved. 
Specifically, 

a.  Use  the  most  descriptive  names  for  data  structures  permissible  within 

the  programming  language,  espeGially  when  such  names  eliminate  the 
need  for  explanatoiy  narrative.  j 

b.  Make  each  further  detailing  of  a data  stnieture  definition  consistent 
with  eveiy  previous  assumption  concerning  its  use.  As  k minimum, 
the  final,  explicit  form  of  a data  structure  definition  must-  contain:  (ii) 
the  stnieture  name;  (ii)  its  mnemonic  derivation;  (iii)  tyfje  attributes 
(e.g.,  real,  string/array  variable,  simple  variable,  etc.);  (iv)  range  of 
values;  (v)  scope  of  activity  (i.e.,  over  what  portions  of  jhe  program 
the  stnieture  is  not  available  for  reassignment  or  reuse  by  other  parts 
of  the  program);  (vi)  description  of  the  use  of  the  data  structure  in  the 
program;  and  (vii)  a list  ol  any  data  structures  that  share  or  overlay 
storage  with  this  stnieture. 
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Gi  declaration  and/or  initialization  of  a new  data  struetuire  may  appear 
as  an  entiy  requirement  of  the  current  module^  to  be  performed  in 
specified,  previously  defined  modules.  Document  such  actions  in  the 
narrative  or  by  annotations  to  the  flowchart  for  the  current  module. 
Locate  the  actual  declaration/initialtzation  code  within  the  specified 
modules  (striped  or  unstriped),  indented  (if  permitted  by  the 
programming  language)  to  show  that  it  is  a later  addition  to  that 
module  (not  eontributing  to  nor  detracting  from  the  previous 
assessment  of  correctness)  and  annotated  to  indicate  the  later  module 
which  requires  this  initialization. 

d.  Data  stnictures  may  be  referred  to  in  striped  modules  in  generic 
terms  when  not  related  to  control^Iogic  correctness,  Assumptions 
made  in  such  references  liiust  be  consistent  with  the  current  state  of 
the  data  structure  definition. 

For  example,  a striped  module  may  state  that  a set  of  characters  is 
“put*'  in  the  *^name  table,**  whereas  an  unstriped  submodule 
which  impieincnts  that  function  must  be  specific,  as 
“nptr-nptrh^i  . NAME  (NPTR)  «N$/’  in  which  NPTR,  NAME,  and  N$  appear 
as  appropriately  detailed  declarations  in  data  structure  definitions. 

e.  Describe  the  form  and  content  of  data  structures,  and  define 
relationships  among  data  items. 

For  example,  one  such  relationship  might  read  “field  2 has 
meaning  only  if  field  1 is  non-zero.** 

8,  Identify  I/O  requirements  that  interface  with  internal  data  structures 
or  other  1/6  requirements.  These  must  be  specific  for  unstriped  modules, 
but  may  be  referenced  in  appropriate  generic  terms  for  striped  modules; 
Specifically, 

a.  An  I/O  interface  is  to  be  defined  so  as  to  be  consistent  with  everj^ 
assurnption  Goneerning  its  use. 

b.  Any  I/O  interface  not  made  specific  at  the  current  level  should  be 
maintained  in  an  appropriate  I/O  Requirements  Table  in  the 
Software  Development  Libraiy  or  Project  Notebar.k.  A complete 
desGription  of  the  I/O  interface  must  eventually  be  included  in  the 
SSD  (see  Section  12.7.4,  below). 

9,  Identify  all  constraints  appropriate  in  the  implementatiGn  of  the 
module,  such  as^ 

a.  Critical  maximum  time  of  execution. 

b.  Data  ordering. 

c.  Machine  timing  characteristics. 
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d.  Special  hardware  features* 

c.  Accuracy  requirement  as  it  relates  to  computer  word  size  and  the 
need  for  single-  or  miiitiple-rpredsion  computation. 


12.7.2  Rules  for  Documenting  Structured  Flowcharts 

As  I indicated  in  SeGtion  7.4,  generating  itowcharts  and  maintaining  these 
by  hand  in  an  evolving  program  design  can  be  time-Gohsuming,  non^ 
productive  tasks.  Yet,  riiany  feel  that  there  is  great  benefit  in  having  such 
charts  for  their  graphic  value.  In  Chapter  17,  1 discuss  automatic 
production  and  maintenance  of  design  flowcharts  from  CRISP-like  source 
statements,  as  a natural,  easy,  flexible  and  productive  way  of  generating 
high-quality  charts^ 

The  rules  given  here  describe  the  format,  content,  cross-referencing 
technique,  etc.,  of  such  charts*  The  detail  level  corresponds  to  “Class  A*’ 
standards  (Chapter  16),  which  may  be  relaxed  during  the  architectural 
phase,  at  projiiect  option. 


1,  Limit  flowcharts  to  one  21-1/2  X 28  cm  (8-1/2  X 11  in.)  page  each, 
except  in  unusual  circumstances,  such  as  when  a single  decision  results  in 
multiple  branches  that  will  not  fit  on  one  page,  and  when  the  symbol- 
striping  convention  only  adds  to  confesion, 

2,  Conform  flowcharts  to  ANSI  Standard  X3. 5-1970  augmented  as  given 
in  Appendix  B;  symbols  should  not  be  varied  in  proportion.  Symbol  text 
should  be  brief,  but  exact.  Use  narrative  accompaniment  to  extend,  explain, 
and  expand  upon  the  symbol  function. 

3^  Give  each  chart  a Dewey-decimalized  number  that  identifies  its 
locaiton  in  the  design  hierarchy,  All  symbols  on  the  chart  are  numbered 
consecutively.  A possible  exception  is  the  numbering  of  GGllecting  nodes. 
The  numbering  system  recommended  is  the  pre-order  traverse  (Section 
51.3,3),  or  top-to-bottom,  left-to-right  order.  The  symbol  number  is  placed 
at  the  upper  right  of  the  symbol. 

4.  Use  cross-reference  identifiers  located  at  the  upper  left  of  flowchart 
symbols  corresponding  to  invoeations  of  subroutines  and  major  program 
segments.  Subroutines  should  use  an  alphanumeric  level-!  identifier.  Major 
program  segments  may  be  given  an  integer  leyel-l  identifier, 

5.  Uniquely  identify  symbols  by  concatenating  their  chart  number  to  the 
symbol  number  (on  the  upper  right).  Thus,  the  symbol  labeled  5 appearing 
on  chart  P4  would  be  designated  P4:5, 
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6,  Enter  the  name  of  a stii|>ed  module  so  that  it  appears  above  the  stripe; 
it  appears  again  inside  the  entry  ‘"bubble”  of  the  flowchart  at  the  next  level. 


Figure  12-16  shows  a set  of  hierarGhically  nested  subpro- 
gram flowcharts,  annotated  in  the  correct  manner.  In  this 
example,  1.2.5. 1.6  refers  to  a striped  box  labeled  6 on  chart 
1.2.5.1  at  level  4 Csince  four  level  numbers  make  up  the 
chart  number).  The  entire  chart  1.2.5. 1 is  an  expansion  of 
the  striped  box  numbered  1 appearing  on  chart  1.2.5  at 
level  3,  which  in  turn  is  an  expansion  of  striped  box 
number  5 of  chart  1,2  at  level  2,  which  is  an  expansion  of 
box  number  2 of  chart  1 at  level  1, 


Figure  12r16.  Hierarchically  nested  subprogram  flowcharts 
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An  unstriped  box,  sudh  as  1,2.5,1*0  in  Figure  12-16, 
indicates  that  further  detail  is  availablfe  only  iii  the 
acGoinpanying  narrative  or  at  the  code  level,  and  the  cross- 
reference,  XBfEFy  if  supplied^  gives  a reference  to  a section 
In  a programming  manual  or  system  manual; 

Striping  eonyeiitions  are  summarized  in  Figure  12-17. 

7.  iDistinguish  subprogram  flowcharts  by  chart  exits  having  a blank 
normal  exit  "bubble,**  of  by  chart  exits  labeled  “EXIT"’  or  *'AeoRir,” 
indicatmg  paranormal  or  abnormal  termination. 

8.  Use  unstriped  process  symbols  to  state  precise,  funGtionally 
unambiguous,  and  explicit  speeifications  for  coding,  as  space  permits.  Use 
narrative  keyed  to  the  symbol  to  explain  or  expand  upon  the  ihaterial  given 
within  the  symbol,  if  needed  for  understanding,  Strive  to  make  the  symbol 
contain  enough  information  for  coding  without  recourse  to  the  narrative,  to 
increase  coding  speed. 

9i  DisMnguish  ^uhrou^ine  function)  fl  owcharts  by  chart  exits  having 
“return”  or  “AhORir*'  in  the  normal  exit  symbol  Each  callable  function  then 
has  its  own  hierarchical  structure,  as  speGified  in  Rule  2,  abeve* 


Cross-referencing  conventions  are  summarized  in  Figure 
12-18*  Note  that  a cross-reference  code,  when  it  appears, 
takes  precedence  over  the  box  reference  code. 


la)  bh  Chart  c.' 


(b) 


Figure  1M7.  Module  Griping  converitipns:  (a)  internal  suk^rogram  or  proced  whose 
expansion  appeam  as  chart  c,n  etoewhere  in  this  sei  of  dbCumenUrtibtt;  (b)  ihtemat 
subroutine  or  major  subprogram  whose  expsnislon  appears  beginning  on  Gharl  X 
elsewhere  in  this  documentation;  and  (c)  external  subprogram  or  tuncticm  whose 
expansion  to  not  flowcharted  in  this  set  of  ddeumentatipn,  but  whose  precise  interface 
speciflcBtibhs  are  gWeii  hr  section  £ of  this  set  of  documentation 


\CMAPJ2 


88  Program  Design  and  Specification  Standards 


10.  Attach  or  append  a table  to  each  top-level  subroutine  flowchart  and 
each  topdevel  flowchart  of  a major  program  segment,  giving  a list  of  the 
cross-reterenees  to  invocation  points  within  the  program,  as  illustrated  in 
Figure  12-18; 

This  table,  filled  in  as  the  design  progresses,  serves  to 
ensure,  in  the  event  that  later  changes  are  made  in  the 
functioning  of  a subroutine,  that  the  side  effects  can  be 
identified. 
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11.  Cross-referenee  the  use  of  a function  within  a symbol  by  :?ither 
placing  the  appropriate  identifier  at  the  upper  left  of  the  symbol,  or  by 
attacshing  a separate  striped  symbol  to  the  invoking  symbol.  Figure  12’19 
illustrates  these  Gross-referenGing  methods.  Cross-references  to  standard 
libraiy  functions  are  unnecessary. 

12.  Annotate  the  entry  line  of  a flowchart  with  any  entry  requirements  to 
be  placed  on  a module  at  an  earlier  documentation  level 


Such  entry  requirements  are  normally  initializations  of 
variables  which  must  be  made  so  that  the  algorithm  of  the 
current  module  is  operable.  Since  the  initializatiGU  pertains 
only  to  the  execution  of  this  module^  and  not  to  the 
modules  at  previous  levels,  the  annotation  lends  readability 
to  the  design,  placing  the  relevant  information  in  the 
relevant  place.  Figure  12-20  shows  an  example.  Additional 
material  usually  appears  in  the  accompanying  narrative. 


Figure  12-19.  Flowchart  convention  for  computations  involving  an  (a)  internally  defined, 
(b)  externally  defined,  or  (c)  standard  library  function  FV^fC  with  argument(s)  list 
(designator  Fn  is  the  cross-refere.nce  chart  number  of  interface  description) 
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tnformathn 


* 


Special 

Exit 

Information 


Figure  12-20.  Annotation  of  flowchart  to  show  conditions  for  entry,  initialization 
Infomnatlon,  and  exit  information 


13.  Indicate  for  each  decision  box  the  explicit  condition  to  be  tested: 
give  the  answers  (as  well  as  meaninghil  explanations  when  it  lends  to 
program  clarity)  on  lines  from  the  decision  box.  Decision  l>oxes  may  not  be 
striped  (see  Figure  12-14). 

14.  Draw  flowchart  branches  to  reflect  left-to-right  logical  consistency: 
for  binary  decisions,  draw  true  (iW  to  the  left  iu\d  fidse  (No)  to  the  right: 
for  multiple  branches,  arrange  decisions  in  a logical  CASE-order,  as  shown  in 
Figure  1^21. 

la  Locate  the  collecting  node  corresponding  to  a decision  branch 
directly  under  the  decision  box  vertex,  as  indicated  in  Figure  12-22,  below, 
even  if  one  of  the  branches  leads  to  an  abnormal  or  paranormal  termination 
rather  than  back  to  the  collecting  node. 

16.  Locate  the  flowline  exiting  from  a loop  directly  below  the  loop-entr)^ 
flowline,  as  illustrated  in  Figure  12^23, 
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Figure  12-21,  Use  of  explanatory  comments  on  decision  branches  to  ctarify  meaning  of 

branching  variable  values 

17.  Place  only  one  arrowhead  on  each  flowline,  at  its*  termination. 

18.  Affix  to  ever)^  flowchart  a configuration-control  Viox,  which  will 
contain  approval  signatures  and  approval  dates  of  the  module  designer,  the 
design  verifier,  and  the  project  manager  or  his  designate. 


12.7.3  Rules  for  Documenting  Flowchart  Narratives 

The  principal  reason  for  having  flowchart-accompanying  narrative  is  that 
the  flowchart  boxes  are  generally  too  small  to  contaiit  both  complete 
specifications  of  the  functions  alluded  to  within  them  and  descriptions  of 
the  significance  of  algorithinic  slops.  The  niics  that  follow  circumvent  this 
lack  by  providing  an  orderly  format  for  writing  down  what  should  be  said 
in  each  box  for  understanding  and  tLssessinent  of  program  correctness. 

I.  Arrange  the  narrative  at  each  level  to  have  the  following  format,  as 
illustrated  by  Figure  12-24  relative  to  the  flowchart  shown  in  Figure  12-25. 

a.  Begin  each  module  descriptioi*  with  its  name,  chart  number,  and  date 
of  latest  change  as  part  of  the  design  document  section  title. 
Identification  information  should  be  placed  in  the  upper  right  corner 
of  each  page.  The  following  configuratioti  is  suggested: 

Chart  Number  (decimal  number) 

Module  Name 

Date  (date  prepared) 

Page of (ideiUifies  the  number  of  narrative  and  flowchart 

pages  for  the  module) 


Figure  ^2-2Z  Consistent  format  for  alignment  of  collecting  nodes  following  decision 

nodes 
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SSD-D0I-S466-SP 


V'lHDNO  ' 
a/7A75V 


5. <4. 4.1)  riNDNO  Procedure 


On  eatcy,  an  input  line  hajt  been  received  into  an  Input  buffet  via  - 
EMSCIIN  <bl4).  The  QNe  ^olnXeR*  LNPTR,  is  positioned  so  as  to  extract  the  ’ 
iltat  charactev’  of  the  line.  . . 


This  procedure  discards  leading  blanks*  if  any,  and  looks  For  an  MBA51G 
statement  hiaaber.*  I£  a statMent  nunber  is  present,  the  dibits  are  con- 
veriad  to  an  Integer  and  placed  in  the  X=^lue  variable  V;  the  Class  variable 
C is  flet  to  13  to  Indicate,  that,  the  first  syribbl  on  the  line  is  an  Integer. 
If  a statement  number  is  not  present.  G is  set  to  0.,  indicating  the  input 
line  dbe.s  not  have  a statement  number;  V tetTlns  its  entry  value,  See 
Table  7, 1.2.5  for  furturr  class  and  value  defln/tionfi. 


On  exlT..  C and  V contain  the  synb?l  Class  and  Value  valueR  above,  the 
Curren'e.  .GHaR&cter  variable,  CCHR,  holds  the  character  which  stopped  the 
dumber  scen7  und  LNPTd  points  to  the  next  Input  character  to  be  fetched.  A 
value  of  V'i‘91J9,999  Indicates  the  Btatenent  nvaaber  is  too  large. 


.1/IU7  GET  the  flrfit  character  ftcun  the  current  input  line  (see  DI5G1N/U14) 
into  CCHR, 


.2/P4  CAXegoritc  CGHR.  If  blank,  seen  to  and  fetch  the  first  non-blank. 
Set  Character  Class,  CC,  and  jdharacter  ^alue,  CV,  as  specified  in 
Table  7.2,-2.5.^  ec  will  be  2 If  GCHR  is  a digit,  and  CV  will  contain 
ica  integer  value. 

.3-, 4 If  the  first  non-blatik  character  on  a line  is  not  a digit,  set  C to 
record  that  no  ststewent  number  la  present,  and  exit, 

,3“ *5  If  the  first  non-blank  character  is  a digit,  set  C to  recotd  that 
a statement  numbet  is  present*  Initlaliaa  V to  the  first  statement- 
number  digit  as  an  integer,  and  set  the  loop  structure  flag  RiHD  SWitch, 
FNMW,  so  ae  to  iterate,  bringing  in  dibits* 

.6-. 14  Bring  in  remaining  digits  and  convert  them  Into  V as  follows.  After 
GETting  each  character: 

,7-i9  If  the  Character  is  blank,  set  FOTSW  to  tcrailnatc  the  scan',  as  the. 
Btatemiiht  number  has  now  beam  extracted*  and  exit. 

.10/P4  Otherwise,  CATegorlae  the  character  seen*  as  in  step  2 above. 

.11-.12  If  not  a dtg.it,  terminate  the  iteration,  and  exit. 

.13/E141  If  CCHR  Is  a digit,  ACCUMulate  its  value  into  V.  SfeL  FNliSW*-!  to 
terminate  the  iteration  If  V exceeds  999,599* 

*14  Iteration  contir.ues  until  all  digits  h.jvc  been  proc-issed  or  until 

overflow  was  detected. 


S«59 


Rgure  12-24.  Sample  narrative  fdrmat  anti  content  for  a module  FINDNO,  shown  in 

Rgure  12-25 


Figure  12-25.  standard  ftowcharl  corresponding  to  narrativ*^  in  Rgure  12-24 

y . 
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b.  Prior  to  the  description  of  the  algorithm  of  the  current  module,  state 
all  assumptions  on  inputs,  common  data,  etc.,  needed  for  understand' 
ing  this  module.  Describe  the  module  functioii  and  its  outputs, 
actions,  and  constraints. 

c.  Key  each  of  the  algorithmie  steps  to  the  symbol  numbers  as  they 
appear  on  the  flowchart;  these  numbers  appear  in  the  left-hand 
margin  of  the  narrative  as  .n.  Subroutines  or  major  subprograms 
invoked  may  be  distinguished  by  attaching  their  cross-referencing 
ieveI-1  chart  number  following  the  step  number,  as  .n/Sm. 

2.  Do  not  include  irrelevant  or  extraneous  information.  Be  brief,  and  do 
not  repeat  information  that  exists  on  the  flowchart.  Use  references  rather 
than  repeating  information  appearing  in  parent  modules  or  in  auxiliai^ 
tables.  Functional  detail  given  in  a parent  module  may  be  repeated,  if 
desired,  however,  when  needed  to: 

a.  Identify  which  subfunctiDns  belong  to  which  symbols  on  the  current 
flowchart. 


b.  Detail  a given  function  into  subfunctidns. 

G.  Clarify  the  current  execution  state  ^for  example,  by  giving  an 
explanation  of  the  meaning  of  a certain  condition  that  has  caused 
entry  to  the  current  module,  etc.). 

The  narrative  need  not  include  a description  of  every  numbered  symbol 
on  the  chart,  so  long  as  the  overall  documentation  is  comprehensive. 
Descriptions  of  groups  of  symbols  can  be  used  when  more  meaningful. 

3.  In  specifying  actions  taken  within  a module,  use  single-spaced  text  in 
the  imperative  mood;  avoid  using  the  passive  voice  except  in  occasional 
explanatory  statements  regarding  interfaces,  conditiGns,  etc. 

For  example,  the  narrative  descriptiop  of  a module 
“parse"'  within  a BASIC  compiler  might  read  as  follow^s: 

“Accept  statements  and  commands  entered  from  the 
terminal  with  normal  or  line  number  prompting,  or  from  a 
file  without  prompting  during  load,  merge,  or  COPY  (to 
workspace).  Parse  statements  and  commands,  and  translate 
statements  into  an  executable  pseudo -op  form.  Terminate 
abnormally  if  errors  are  found,  print  an  appropriate  error 
message,  and  return  to  the  command  mode.*’ 

4.  Use  descriptive  mnemonic  names  for  all  data  structures.  Provide  the 
mnemonic  derivation  of  a|l  data-stnicture  names  used  in  a module  at  least 
once  (at  its  first  top-down  appearance).  Names  appearing  in  tier  chait 
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*‘Gousin”  modules^  unreferenced  in  any  of  their  common  ancestors,  should 
repeat  the  mnemonic  definition  iii  each  such  module. 

5.  Insert  annotations  or  cross-referencing  information  so  as  to  make  a 
correspondence  between  speoifie  detailed  requirements  or  functional 
specifications  and  the  current  algorithm  being  dccumented  when  such 
information  has  not  been  included  at  a preceding  level 

6.  Explain  the  significanGe  of  each  path  following  a decision,  or  the 
conditions  assumed  to  be  in  effect  at  such  points. 

7.  Include  statements  that  provide  rationale,  assumptions^  or  other 
clarifying  explanations  of  the  algorithm  as  heeded  to  lend  meaning  and 
readability  to  the  text  Describing  the  intended  significance  of  an  action 
(such  as,  for  example,  setting  or  testing  a flag)  can  save  a reader  much  time 
in  understanding  what  that  algorithm  is  supposed  to  do.  It  is  important  to 
provide  such  information  for  every  loop,  stating  what  assumptions  are  valid 
during  each  iteration  (i.e.,  the  loop  invariant). 

12.7.4  Rules  for  Documenting  Data  Structures  and  Resource 
Access  Requirements 

Documentation  of  the  data-structure  development  hierarchy,  or  other 
resource-access  requirement  hierarchies,  is  a dynamic  process  that  requires 
visibility  and  interfacing,  usTiatly  across  wide  segments  of  the  development 
project.  The  evolution  of  a data  structure  design,  for  example,  can  be 
maintained  in  a Data  Structure  Definition  Table  (DSDT)  in  the  Software 
Development  Library  or  PLoject  Notebook.  When  tlie  definitions  are 
complete,  they  are  converted  into  formal  descriptions  in  the  SSD. 


The  rules  of  this  section  are  aimed  at  making  the  cdneiirrent 
documentation  of  such  evolution  compatible  with  later  more  formal 
inclusion  in  the  SSD,  Consult  Section  12.7.1,  Rules  7-9  for  information 
concerning  table  content. 

1.  Maintain  the  current  level  of  hierarchic  detail  for  data  stnictures  or 
other  resource  access  requirements  in  the  most  flexible  and  visible  form 
available. 


The  use  of  7-1/2  X 12-1/2  cm  (3  X 5 in.)  cards  or  pages 
in  a loose-leaf  notebook  (each  table  beginning  a new  page 
or  card)  or  c omputer  files  maintained  by  the  SDL  permits 
good  expansion  and  revision  capability. 
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2.  Mdke  an  entry  into  the  DSDT  for  each  data  structure  Gr  resource 
requirement  referred  to  in  general  terms,  or  in  any  way  other  than  its  name. 
Later,  augment  the  DSDT  to  state  the  actual  structure  name. 

3.  Strive  to  make  tables  provide  explicit  specifications,  or  else  give 
references  to  such  material  elsewhere,  either  in  the  SSD  or  in  external 
documents.  Organize  DSDT  entries  in  alphabetic  order  by  mnemonic  name 
for  ease  in  locating  stnictures  referred  to.  An  example  of  a DSDT  entry 
appears  in  Figure  i2-26. 

4.  Include  graphical  displays  and  narrative  descriptions  of  data  structures 
and  other  resource  access  definitions.  These  should  not  only  describe  the 
composition  and  format  of  the  data  structure  or  other  resource  accesses, 
but  should  also  describe  the  operations  (or  level  of  access)  performed. 


12.7^5  Rules  for  Documenting  Structured^Ehglish  Procedural 
Specifications 

Besides  flowcharts  and  accompanying  narratives,  there  are  other 
techniques  to  design  and  display  procedures  in  a two-dimensional 
structured  form  and  explain  what  is  going  on;  I mentioned  the  of 
GRTSP-PDL  in  Section  7.4  as  a simple,  effective  procedure  design  lanj^jage. 
This  .section  provides  a few  niles  for  using  such  a technique  either  as 
augmentation  or  as  an  alternate  to  the  material  in  Sections  12.7.2  and 
12.7.3.  Tf  used  as  an  alternate,  then  CRTSP-PDL  should  conform  to  the 


SEGNO  SEGmem  number  (NO),  flag  variable  (range:  3-9)  first 
assigned  in  SYSUP  (module  2).  Value  specifies  the 
configuration  currently  active,  or  next  to  be  actk 
vated  after  configuration  by  USWAP  (module  Ul),  as 
detailed  in  the  table  oeldw.  SEGNO  is  active  through- 
out the  entire  program  except  for  the  subprogram 
EXIT  (module  9). 


SEGNO  = ? 

Configure  for 

3 

SVSiZL 

4 

PARSE 

5 

RUNiZL 

6 

RUN 

7 

BATCHC 

8 

BATGHR 

9 

EXIT 

Rgure  12-26.  Example  of  a Data  Structure  Definition  Table  entry 
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discipline  of  both  of  these  sectioasi  as  appropriate.  As  a preliminary  design 
or  look-ahead  tool,  the  rigors  may  be  more  relied.  A skeleton  example  is 
shown  in  Figure  12-27,  and  an  SSD  entiy  appears  in  Figure  12-28, 

1.  Structure  the  specificatiGn  of  program  algorithms  into  ii  hierarchic, 
top-down  syntax  using  the  control  language  of  Appendix  G superimposed 
on  simple  English  language  constnictions.  Use  indentations  and  cosmetics 
to  display  the  nesting  structure  as  indicated. 

2r  Limit  each  such  specification  to  one  page  by  inventing  named 
procedural  subspecifications  for  expansion  at  the  next  hierarehic  level. 
These  named  subspecifications  will  be  referred  to  as  striped  modules,  just  as 
if  they  appeared  on  flowcharts. 

3.  Begin  each  striped  module  algorithmic  description  with  its  name, 
identification  number,  and  date  of  latest  change, 

4.  Affix  to  each  module  a configuration-control  box  for  concurring 
signatures  (or  initials)  and  dates  of  the  module  designer,  design  verifier,  and 
project  manager,  or  his  designate, 

5.  Prior  to  the  description  of  the  algorithm  of  the  current  module, 
provide  a comment  block  that  states  all  assumptions  on  inputs,  common 
data,  etc*,  used  by  this  module  and  visible  in  the  algorithm.  Describe  the 
module  function  and  its  outputs,  action-i,  ynd  constraints. 

6.  Number  each  step  in  a procedure  in  numerical  order  from  the  top 
down,  except  for  perhaps  I^NDIF,  ENDCASES,  JOIN,  etc.,  which  represent 
collecting  nodes  at  the  end  of  flowcharted  structures.  Afiix  this  number  to 
the  statement  beginning  at  the  left  margin  and  preceded  by  a period  (see 
Figure  12-27), 

7.  Assign  to  each  subprogram  striped  module  a unique  Dewey-decimal 
identification  code.  This  code  is  made  by  concatenating  the  step  number, 
where  that  subprogram  is  invoked,  with  the  current-module  identification 
Gode^ 


Thus^  for  example^  if  step  3 of  module  1.4.6  invokes  a 
subprogram,  that  subprogram  is  given  the  identification 
code  1.4.6.3*  Note,  also,  the  use  of  the  virgule  in  Figure 
10-27  to  rename  subprogram  1.8  as  subprogram  3. 

8.  Assign  to  each  subroutine  striped  module  a unique  alphamimeric  code 
as  its  level-1  cross-referencing  symbol,  Annotate  each  procedural  step  n 
where  a subroutine  is  called  by  placing  the  subroutine  number  Sm 
foliowihg  the  step  number,  separated  by  a virgule,  as  .n/Sm. 
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Module  1 
CRISP-X 
5 Feb  75 
page  t of  V 

PROGRAM:  CRISP  Processor 

<*Th»S  Jriodule  Is  the  top-level  preltmtnary  desion 
<*of  a GfllSP  translator  for  an  arbitrary^  as-yet 
<*unspecified  unstructured  lower-level  language,  X. 

< * The  chflracterrstlcs  of  this  translator  are 
<* forth  in  Appendix  G of  this  text.  No  coding 
<*  language  for  this  program  has  yet  been  chosen, 

<*and  codability  of  this  design  has  not  specifically 
<*been  considered.  This  documentation  is  for 
<*  architectLiai  studies  only  . 

,1  Initialize  the  processor 

.2  loop 

.3  ! ^ Accept  control  parameters 

.4  I ^ Configure  as  necessary 

.5  ! (control  says  EDIT  mode) 

.6/2  I : do  perform  source  editing  <*  Note:  edit 

1 : <* functions  are  not  included  in  Appendix 

1 : <*  G;  this  stub  is  a hook  into  an 

I I <*  envisioned  later 'apability*> 

.7  1 :-> (control  says  PDL  mode) 

.8/3  ! : do  Cosmetize  arid  list  the  program  descriptions 

.9  ! :“->{control  says  FLOW  mode) 

JO/4  ! : ^ Draw  flowcharts  of  the  program  descriptions 

.11  ! :->  (control  says  X-transtate  mode) 

J2/5  ! : ^Trahslatesource  descriptions  into 

I : language  X 

! : . . endif  < ” control  option  may  skip  al  I the  above  * > 

.13  1 , . repeat  uhlew  (control  says  go  on) 

.14/6  it  (contror saysload-and-go)  ^ Link  target  code 

: to  its  compiler,  compiler  output  to  loaders,  and 

: . . tell  loader  to  initiate  execution  of  Job. 

J5  ^ Glean  up  required  for  exit 

eridprogram 


Rgure  12-27.  A conceptual  leveFI  design  description  of  a GRjSP  preprocessor  using 
CniSP*PDL*like  language  (several  features  that  will  be  required  later,  such  as  error 
response  and  recovery,  have  been  neglected  at  this  stage  of  design;  as  given,  this 
description  probably  represents  Class  G or  D preliminary,  or  “look-ahead/’  design 
documentation,  not  suitable  for  formal  specifications) 
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Module  1 
CRISPFLOW 


23  Sept  76 
page  1 of  1 


5|1 ) eRISPPLOW  Detailed  Design:  Main  Program  Hierarchy 


PROGRAM:  GRISPFLOW <*23 Sept 76*>  MOD#  1 

<* This  is  the  top  leyel  diagram  of  the  GRISPF LOW 
< * processor  See  Section  2 of  this  softv/are  speci- 
<*ficatlon  document  for  program  description  standards 
<*and  conventions.  Section  3 for  environment  and 
<* interfaces,  Section  4 for  functional  specifications 
<* including  I/O,  and  Section  5,0  for  an  overview  of 
<*  proccssih9  and  supporting  data  structures. 


.1 

.2 

,3 

.4/SI 

.5 

,6 


.7 

.8 

.9 

.10/SI 

.11 

.12 


DO  GR1SPFL0W_  INIT  <*  Declare  and  initialize  all  global 
< * data  structures  * > 

DO  OPEN._IO_MEDIA  <*Open  necessary  I/O  and  set  options *> 
Set  EOS  = %FALSE  <*end-bf-source  f!ag*>, 

ERRFLG  = % FALSE  <* processing  condition  flag*> 

CALL  GETLINE  (INBUir  ^ER,  EGS)  <*Set  EOS  true  If  no  line  left 
<*  in  source  medium*  > 

LOOP  WHI  LE  |EOS  = %FALSEX*until  end  of  source  input *> 

I DO  PARSE  <*  Bring  in  module  and  build  TREE 
I <•  Output  an  error  message  and  set  ERR FLG  true 
! < * if  a module  cannot  be.  flowcharted  as  per 

! < * section  4 of  this  SS  D * > 

1 IF  (ERRF LG  ^ %FALSE)  <*  If  module  was  acceptable*> 

! : DO  LAYOUT  <*  allocate  sizes  and  coordinates  *> 

1 : DO  DRAW  <*  Draw  the  flowchart *> 

! : . - ENDIF  <* otherwise,  ignore  the  module *> 

I CALL  GETLINE  (INBUFFER,  EGS)  <*get  next  input  line 
I . . REPEAT 

PRINT  '"FLOWCHARTING  COMPLETE" 

DO  CLOSE  10  MEDI  A <*Clean  up  for  terminatiQn*>  | 
ENDPROGRAM 


Figure  12-28.  A GRISP-PpL  description  of  the  top-teyel  specification  for  the 
CRISPFLOW  processor  described  In  Appendix  G 
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Thus,  for  example,  if  step  3 of  module  1.4,5  calls  a 
subroutine  P6  named  PLOT,  then 
3/p6  GALL  PLGT{xdata,  ydata)'* 
may  appear  as  the  procedural  step  description. 

9;  If  internally  defined  function  calls  occur  in  a step,  attach  their  leveH 
number  codes,  as  in  rule  above,  to  the  step  number  as  well,  as  room 
permits. 


For  example,  if  RIGHT  is  a fiinction  nunibered  NS,  then 
“ . 3 /N5  SET  TOKEN=RIGHT  (TOKEN)  “ 

may  appear  as  a procedural  step. 

10.  Make  all  conditional  tests  explicit  (i.e.,  ho  striped  decision  modules). 
Annotate  the  steps  corresponding  to  test  outcomes  with  meaningful 
explanations  of  that  outcome.  Note  that  the  description  In  Figure  12“27  has 
not  adhered  to  this  rule,  being  a look-ahead  design.  Figure  12-28,  however, 
being  an  SSD  entty,  has  conformed. 

11.  Do  not  include  irrelevfMit  or  extraneous  information  in  describing 
procedural  steps.  Be  brief,  using  references  to,  rather  than  repeating, 
information  appearing  in  parent  modules  or  in  auxiliary  tables.  No 
functional  information  given  in  a parent  module  need  be  repeated,  except 
as  needed  to 

a.  Identify  which  subfunctions  belong  to  which  steps  in  the  current 
algorithm. 

b.  Detail  a given  function  into  subfunctions. 

c.  Clarify  the  algorithm  (for  example,  by  giving  an  explanation  of  the 
meaning  of  a certaiiv condition  that  has  caused  entry  to  this  module). 

Use  the  imperative  mood  to  specify  actions  taken  within  a module, 
and  use  single-spaced  text  to  describe  steps.  Double  space  between  steps,  if 
desired,  to  group  sets  of  steps  for  readability. 

13.  Use  descriptive  or  mnemonic  names  for  all  data  stnictures  referenced. 
Provide  the  mnemonic  derivation  of  each  data  structure  name  appearing  in 
a module  at  least  once  (at  its  first  top-down  appearance).  Names  appearing 
in  '‘cousin’'  modules  of  the  tier  chart,  unreferenced  in  one  of  their  common 
ancestors,  should  repeat  the  mnemonic  derivation  in  each  submodule. 

14.  Insert  annotations  or  cross-referencing  data  so  as  to  make  a 
correspondence  between  detailed  requirements  or  functional  specificutions 
and  the  algorithm  being  documented,  when  such  data  has  not  been 
included  in  the  description  of  that  module  at  a preceding  level. 
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15.  hKiude  statcmerkts  that  proyido  rationale,  assumptions,  or  other 
clarifying  expkitritions  of  the  algorithm  Steps  as  needed  to  lend  meaning 
and  readability  to  the  text 

16.  Provide  cro.^s-'referenGcs  for  each  subroutine  which  locates  all  calls  to 
that  subroutine.  This  materia!  is  used  to  aid  in  identifying,  in  the  event 
changes  are  made,  where  role  side  effects  may  be  likely  to  occur. 


12.8  RULES  FOR  THE  SCFTWARE  DEVELOPMENT 
LIBRARY 

1.  Make  the  SDL  the  central  repositoiy  for  aK  textual  and  graphic  design 
material,  be  ft  working-level,  look-ahead,  or  approved  documentation. 

2.  Accept  design  modules  into  project  control  only  from  the  top  down. 
Keep  a tier-chart  log  of  module  status  which  includes: 

a.  Date  of  submittal, 

b.  Date  of  acceptance. 

e.  History  of  design  changes  or  proposed  changes. 

d.  Assigned  phase  of  development 

3.  Publish  regular  reports  regarding  project  status  that  reveal  progress 
relative  to  the  work  breakdown  structure,  modules  completed  during  the 
reporting  period,  the  cumulative  number  of  total  modules  completed,  and 
the  number  of  identified  stubs  at  future  levels  which  are  to  be  yet  supplied. 
Flag  modules  with  apparent  discrepancies,  such  as  those  having  erroneous 
module  numbers  or  names,  those  being  supplied  or  worked  on  in  the  wrong 
development  phitse,  and  those  with  recognized  anomalous  behavior. 

4.  Distribute  copies  of  design  materials  to  team  members  upon  request. 
Do  not  permit  master  copies  of  approved  modules  to  be  altered  without 
approval  of  the  project  manager.  The  SDL  keeps  the  official  master  copy  in 
all  cases. 

5.  Maintain  a file  of  standards  waivers,  and  provide  periodic  summaries 
of  waiver  activity  to  the  project  manager. 

6.  Disseminate  standards  information  and  materials  within  the  project, 
and  train  new  employees  in  the  use  of  these  standards. 

7.  Use  available  avitomatic  or  computer-aided  means  for  the  creation, 
update,  and  monitoring  of  design  documehtation.  Implement  policies 
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whereby  team  members  may  interact  openly  with  the  design  base,  but 
which  discourage  team  members  from  keeping  their  efforts  invisible  or 
private. 


In  the  Chief  Programmer  Team  concept,  for  example,  the 
programming  secretary  enters  all  information,  coding,  and 
testing  into  the  computer;  no  others  are  permitted  access 
to  the  compxiter.  Such  a policy  may  be  necessary,  in 
austere  cases,  merely  to  make  programming  a public 
practice. 

8.  Maintain  a file  of  all  action  items  levied  by  design  reviews,  with  the 
current  disposition  of  each. 

9.  Audit  all  documentation  submitted  for  approval  for  adherence  to 
standards. 

12.9  SUMMARY 


This  chapter  has  put  forth  standard  disciplines  that  encourage  software 
design  as  a hierarchic  layering  of  detail,  both  in  the  invention  of  controb 
logic  algorithms  and  data  structure  abstractions;,  to  focus  attention  to 
relevant  details,  and  to  hide  irrelevant  details,  at  each  point  in  the  design 
synthesis,  I have  tried  not  to  orient  these  disciplines  toward  any  particular 
programming  language,  existing  or  envisioned,  but  toward  the  thought 
processes  during  the  design  process,  and  toward  documenting  the  results  of 
that  process  in  a way  that  is  sufficient  and  useful  throughout  the  entire 
software  life  cycle. 

Further  discussions  on  the  de.sign  medium  and  automatic  aids  to  design 
may  be  found  in  Chapter  17  and  Appendix  G.  Samples  of  the 
documentation  styles  appear  in  Appendix  L, 
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Once  the  program  algorithms  have  all  been  specified,  the  data  structures 
all  defined  and  laid  out,  and  the  T/O  interlaces  all  fixed,  what  essentially 
remains  is  the  design  of  code  to  implement  the  “unstriped  modules^  of  the 
SSD  and  linkages  to  and  from  striped  modules.  The  activity  of  concurrent 
coding,  however,  requires  a bit  more  than  mere  rote  translation  of  the 
design  specification  into  statements  of  executable  code,  modularly 
programmed  to  conform  to  the  hierarchic  design  levels.  Tn  practical 
application,  there  arc  usually  many  accommodations  that  must  be  made 
before  the  coding  can  even  get  underway.  Generally  speaking,  the  methods 
here  recommend  that  code  be  generated  in  an  execution  sequence;  for 
example,  job  control  code  first,  then  linkage  editor  code,  then  module 
linking  code,  and,  finally,  code  for  the  design  specifications. 

This  chapter  presents  a set  of  mles  for  producing  and  documenting  only 
the  code  specified  in  the  SSD.  These  rules  are  based  on  the  premise  that 
noticeably  more  efficient  programs  result  more  from  design-level 
considerations  than  from  coding-level  considerations,  and  that  faithful 
coding  of  the  design  is  of  paramount  importance. 
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13.1  RULES  FOR  CODING  STRUCTURED  PROGRAMS 

At  the  onset  of  coding,  all  data  stnictures  and  other  design  mechanisms 
will  have  been  descril)ed,  at  least  to  the  degree  required,  in  a set  of  self- 
contained,  cross-referenced,  docmnented  specifications  (the  SSD)*  In  the 
rules  that  follow  iii  this  section,  I have  assumed  that  one  is  coding  from 
flowcharts  and  narrative,  although  one  could  as  easily  be  coding  from 
CRTSP-PDL  specifications,  {in  fact,  as  will  be  seen  in  Chapter  17,  the 
dividing  line  between  such  ‘‘design  specifications”  and  “coding”  in  my 
“standard  production  system”  is  somewhat  artificial  because  of  this.) 

Recall  that  striped  flowchart  symbols  at  one  tier  of  the  design  were 
expanded  into  procedures  at  later  levels,  and  that  unstriped  symbols  were 
constrained  to  be  codable  without  functional  ambiguity— any  method  of 
coding  such  a submodule,  as  long  as  the  code  performs  as  specified  in  its 
unstriped  description,  must  worlc. 

Let  me  make  a distinction  at  this  point,  and  for  the  remainder  of  the 
chapter,  between  a “code  module”  and  a ‘‘code  submodule,”  for  the 
purposes  of  describing  the  program  code.  By  a code  modtde,  T shall  mean 
all  of  the  code  that  corresponds  lO  a “flowchart”  or  a flowchart  symlro!  and 
all  its  hierarchic  descendent  striped  submodules,  including  any  subroutines 
that  pi^rhaps  may  used  totally  within  the  code  module,  and  not  outside. 
By  a code  subm{?dule,  f shall  refer  only  to  the  code  that  appears  explicitly 
for  coding  a single  flowchart  Whenever  a striped  .symbol  appears  on  a 
given  flowchart  then  only  the  linkage  (if  any)  to  the  remainder  of  the  code 
for  that  striped  symbol  will  be  counted  as  part  of  the  code  submodule. 

Thus,  for  example,  the  code  submodule  MBASIC^^  depicted  in  Figure 
13-1  po.s-.sesses  les.s  than  one  page  of  code;  the  entire  MBASIC^^^  code 
module,  however,  con.si.sts  of  tens  of  thousands  of  code  instructions. 

Let  me  also  distingui.sh  code  modules  and  submodules  from  “compile 
module.s  ’ A compile  module  is  a set  or  subset  of  code  modules  and/or 
submodules  that  are  compiled  together  as  a unit  for  any  reason,  such  as  to 
provide  a level  of  access  to  a data  structure,  to  segment  a program  into 
overlays,  and  so  forth.  The  grouping  of  code  .submodules  into  compile 
modules  i.s  part  of  the  code  design,  and  much  of  it,  if  not  all,  will  be 
dictated  by  the  program  specification. 

By  definition,  the  term,  “coded,”  a,s  used  here,  means  that  the  unit 
referred  to  has  been  translated  into  a computer  language,  exists  in  a 
machine  readable  medium,  and  contains  no  s>mtax  errors. 
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The  following  ruiej>  are  guidelines  for  the  generation  of  erode  modules 
and  submodules  for  sfcnictured  designs. 

1;  BecQine  thoroughly  familiar  with  the  overall  design  philosophy  and 
conventions  before  coding  begins, 

ii.  Establish  project-wide  coding  standards  for  Use  macros  or  other 
style  conventions  only  when  these  are  accepted  and  used  as  project 
standards.  Confomn  all  situations  where  such  standards  apply  ruthlessly  to 
the  siandiird,  with  deviations  only  on  an  approved  waiver  basis. 

3.  Make  coding  a direct  translation  of  the  flowchart.  Code  programs  into 
a format  conforming  to  and  refiecting  the  structured,  hierarchic,  top-down, 
modular  design. 

Nonnaliy,  code  unstriped  symbols  as  in-line  code,  and  code 
striped  symbols  (references  to  procedures)  as  linkages  to 
separate  procedure  modules  (unless  timing  or  memory  is 
critical  and  such  linkages  are  significant— see  Rule  6, 
below).  Figure  X3-1  illustrates  the  one-to-one  correspon- 
dence between  flowchart  and  code  for  an  assenibiy- 
language  snlimodiiie. 

4.  Set  standard  invoking  (or  calling)  sequences  for  subprograms, 
subroutines,  and  abortive  branches,  especially  if  these  iiivolve  recursive  or 
reentrant  linkages.  Prove  that  such  techniques  work  independently  of  the 
program  module  being  developed. 

Code  e;'ieh  flowchart  as  a separate  code  siibinodule  or 
inaero  proeediire  using  the  most  efficient  linking  method 
available  in  the  prograriuning  language.  Specifically,  if  the 
linking  method  makes  use  of  a stack  to  hold  arguments  or 
return  linkages,  and  if  abnorinal  terminations  lead  to 
reinitialization  of  the  program,  make  sure  that  the  linkage- 
stack  is  also  reinitialized  (notice  that  this  is  done  in  Figure 
13“l).  When  linking  modules  using  the  mechanisms 
provided  by  a higher  level  language,  it  may  be  necessary  to 
know  hovv  these  mechanisms  are  inipiemented  (viz., 
whether  a stack  is  used)  in  order  to  provide  the  proper 
reinitializations  required  by  abnormal  termination. 

5.  Limit  Goding  to  clear,  coneise  code  that  will  be  easy  to  check,  dehiig, 
and  modify.  Avoid  codingdevel  optimizations  that  decrease  clarity.  If  more 
optimal  code  is  needed^  then  clearly  annotate  the  listing  so  that  the  code 
remains  an  accurate  representation  of  the  procedure  specification.  Do  not 
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TITLE  M8AS1C  ,.*,*,****»♦♦♦♦♦* 

# MBASIC  3/20/75  # 

J RCT  3/21/75  I 

* RSH  3/21/75  * 

tfiilr  ^ Jr  * Ki  ^ 4 4^*4  >!«  * * *9*  •:  * * 4 4 ♦ + ♦ 4 4'4  4**444  v 4*4* 
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DO 
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DO 
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initialize  module  linking  PTR 
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.1/2 

.2  RE  IN  IT  MODULE  LINKING 
PTR  UPON  ERROR;  SET 
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Figure  13^1^  Carrespandence  between  flowchart  and  code  for  a module  MBAS1C^^/1 
(Oie  language  le  PDP*10  MAGROrlO  (assembly  language);  the  preamble  prior  to  the 
enti^  label  ahnoimces  to  the  assembler  that  this  is  a reentrant  program  end  dielfinea  the 
symbol  and  macro  definition  files;  DO  is  a 8tHped-ihodute'‘lfnkage  macro) 
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us^  obscure,  undocumented,  or  uhmaintained  feature  of  some  instruction 
sets  or  operating  systems. 

6.  Code  procedure  instructions  so  as  to  remain  fixed  during  execution;  do 
not  write  code  that  modifies  itself.  Sharing  lUemoiy  by  core-swapping  is 
permissible,  however. 

7.  Code  striped-module  subprograms  or  subroutines  as  incline  procedures 
only  whenever  (a)  execution  time  or  storage  is  a eritical  parameter,  db)  the 
execution  time  or  storage  for  the  Galling/return  sequence  is  nournegligiblfe, 
and  (g)  the  hmction  Is  not  used  so  many  times  in  the  program  that 
repetitions  of  in-line  code  would  create  a burden  bn  the  mempiy 
requirements.  Use  macros  to  define  such  in-line  procedures,  when  available. 
Otherwise,  program  such  functions  as  in  Rule  3,  above. 

8.  Use  the  same  symbblic  names  for  procedure  eittiy  points,  variable 
names,  etc.,  as  appear  in  the  program  procedural  design,  if  permitted  by 
the  itnplementation  language.  Clearly  annotate  listings  when  alternate 
names  or  labels  have  had  to  be  used,  and  create  a glossary  of  such 
correspondences^ 

9.  For  operations  that  act  on  data  stmctures,  pass  only  the  field  or  fields 
necessary  for  that  operation  to  acconiplish  its  function^  rather  than  moving 
the  whole  structure  or  ^bstriicture. 

If).  If  correctness  assertions  have  been  supplied  in  the  procedural 
Spectfication,  then  insert  code  to  check  these  assertions  at  runtime.  If 
possible,  make  such  code  a compile-time  option  that  can  be  overridden  or 
removed  from  the  object  program  after  checkout  is  complete;  however,  do 
not  remove  this  code  from  the  source  code,  as  later  modifications  may 
require  it  in  further  checkout. 

11.  Insofar  as  possible,  put  all  implemeritationrdependent  parameters  or 
conipile-parameter  options  together  iii  one  place  in  the  code<  Identify  these 
as  such^  and  give  a prescription  for  changitig  them  should  the  parameters 
require  alteration. 

12.  When  using  a programming  language  w permits  several  data 
structure  names  to  refer  to  the  same  or  overiappitig  storage  struetures  (e^g., 
by  way  of  the  EQUiVALENGE  statement  in  FORTRAN)^  coiifihe  the 
configurations  so  that  no  more  than  one  of  the  data  structure  names  is 
active  at  one  time.  Enter  the  names  of  each  data  stnicture  #^tng  the  same 
storage  appropriately  in  the  code  dbeumentatibn.  Do  not  reference  the 
same  data  structure  within  its  active  range  by  two  diferent  names  unless 
the  conventions  are  so  documented  as  coding  standards  and  enhoAce  the 
readability  of  the  code. 


Scc»  23. 1]  Coding  Structured  Programs 


91 


An  example  where  such  equivalences  might  be  considered 
acceptable  is  the  CRISP  program  that  appears  in  Figure 
13-2.  In  the  example,  stnieture  flag  names  *‘end„qf^LINE'* 
and  “end^qf_input'"  in  the  specification  are  coded  as 
references  to  a loop-eontrcil  stack  implemented  as  the  array 
FLAG. 


13,  Code  the  flowchart  boxes  such  that  the  code  for  nodes  of  the 
flowchart  appear  in  the  same  order  as  a pre-order-traverse  list  of  the  graph 
nodes,  (This  nile  assumes  the  flowchart  hiis  been  drawn  with  branches  in 
case-order  from  the  left.)  The  step  numbers  then  fall  in  sequence  down  the 
page  (see  Figure  13-1). 


^>END_0F_L1NE  MEANS  FLAGCPl- ^-TRUE  'LEND 
LEND_OF_lNPUT  MEANS  f LA&CP)="TRUE  %END 
tPUSH  MEANS  FLAGCP>=“  FALSE  'LEND 

tjPULL  MEANS  P=P“l  iEND 
^LFALSE  MEANS  0 lEND 
'•LTRUE  MEANS  I 1.END 


'(.PUSH 

LOOP  until  c '-lend  ..of  inputs 


: 1,PUSH 

1 LOOP  UNTIL  C uEND_0F_L1NE? 


I ! , * RE PEAT 
: 'iPUiLL 


V . * REPE  AT 
^.PULL 


Figure  A CRISP  program  segment  that  u^s  macros  to  rename  specified  dma 
structure  names  as  reusmoile  stack  locations 
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Take  care  to  assure  that  external  system  subroutines  which 
have  both  normal  and  paranormal  or  abnor>nal  returns  are 
coded  to  conform  with  the  prescribed  flowchart  structures 
(see  Figure  13^3). 

14.  When  coding  in  a language  requiring  jumps  to  aebieve  structure, 
establish  named  labels  for  all  locations  branched  to,  sUjCh  as  decision 
collecting  nodes,  loop  coHeeting  nodes,  and  procedure  I entries.  Set  a 
standard  for  generating  these  names  that  does  not  conflict  with  names  of 
variables  used  in  the  desigri.  Do  not  use  “current  locaticn  ± n"  as  branch 
targets  even  if  permitted  in  the  coding  langiiage. 


OPEN 

2,PGM.T1; 

,6/M. 4.2 .3 

vIRSr 

PGM,  8; 

ERROR  RETURN 

ORST 

PGM  , 7 ; 

NORMAL  RETURN 

PGM.Ti: 

0; 

SPEC t FTC AT XO NS 

SIXB1T/MTA0/J 

FOR  BEVXCE 

XWD 

0,HAGBUF; 

AND  INPUT  BUFFER 

PGM:.  7 : 

DO 

READMG; 

.7  NAME  SHORTENED 

JR.ST 

PGM. 9; 

PGM,  8: 

DO 

W.HTEV  R ! 

.8  NAME  SHORTENED 

PGM* gr 

# - . 

Rgum  134.  Usage  of  a aystain  roinina  mat  has  '^normal"  and  ^'error  return'*  points  (the 
code  is  POP-10  assembly  language;  the  crods«iet£refice  in  box  6 Is  to  the  Monitor 
manual^  Section  A2j3rb0ia  me  smped-module4inkage  macro) 
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15.  Strive  to  loc^ize  the  scope  of  variables  within  each  code  module 
when  supported  by  the  programming  language.  Pass  data  to  subroutines 
normally  as  arguments;  when  arguments  prove  infeasible^  then  pennit  links 
to  global  or  common  pools.  Do  not  permit  content  coupling  between 
separate  compile  modules  (see  Section  4^4). 

16.  Define  named  constants  and  compiler  parameters  to  indicate  purpose^ 
rather  than  value.  Use  separate  constants  (parameter  names)  for  different 
purposes,  even  if  some  of  these  have  the  same  values,  for  later 
modifiability.  Avoid  the  use  of  '-magic  huntbers,"  or  numbers  whose 
meanings  arc  not  implied  by  their  value. 


17.  Use  literal  values  only  if  these  are  tnily  constants  in  the  problem. 
Literals  should  not  be  used  to  address  data  structures  by  making  use  of 
assumed  structural  formats,  especially  if  this  will  limit  the  extendabilify, 
modifiability,  or  flexibility  of  the  code  being  written^ 

For  exaihple,  if  the  third  word  of  an  array,  re^rd,  contains 
a field  to  be  accessed,  do  not  use  such  devices  as  “GET 
REGonp(3)  ,”  because  the  regord  format  is  likely  to  change 
eventually. 

18.  Set  standards  for  representation  of  primitive  and  extended  data  types. 
For  example,  set  a common  convention  for  true  and  false  tests  throughout 
the  programt  if  not  already  a part  of  the  language  sjTitax. 

19.  Set  standards  that  relate  preferred  methods  for  coding  to  enh^^nce 
speed  or  memory  usage,  such  as  indexed  vs.  indirect  addressing,  register^o- 
register  vs.  register-to-meipbty  operations^  byte  access  methods,  ceding  the 
normal  branch  as  the  higher-speed  conditional  branchy  etc. 

20.  Avoid  passing  program  labels  os  arguments.  Such  practice  implies  the 
intention  to  use  that  label  as  a control  branch  target,  and  assessment  of 
control  coirectness  is  thereby  made  more  difficult. 


13*2  RULES  FOR  CODING  STRUCTURED  REAL-TIME 
PROGRAMS 

The  st mctiire  imposed  upon  real-time  programs  by  design  specifiGations 
is  modular  partition  into  sequential  act ivities  which  can  be  coded 
separately  and  then  combined  for  execution  In  a way  that  should  allow  for 
correctness  to  be  asse^cd^  The  following  rules  for  coding  real-time 
programs  augment  those  given  in  the  previous  section. 
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L Determine  methods  to  be  used  and  esitablish  standards  to  provide 
arhitrution  among  resourees  as  required  in  the  desiga  Code  and  validate 
such  meaas,  as  a general  nile»  before  coding  any  part  of  the  program 
making  use  of  these  features.  (Note:  top-down  design  is  still  in  effect  here; 
some  bottom-up  coding  may  be  required,  however). 

2,  Locate  the  code  bodies  for  concurrent  processes  appearing  within  the 
same  program  in  conformance  with  the  same  standards  set  for  non-real- 
time program  segments  in  Rule  13  of  Section  13.1,  Make  the  code  conform 
to  procedural  specificatiGns  in  a one-to-one  identiffable  (and  QA  auditable) 
way,  step-by-step,  module-for-module. 

Consult  Appendix  G for  FORK- JOIN  jmd  WHEN  structures.  If 
program-operated  dedicated  traps  appear,  code  these  to 
conform  with  the  AT  structure. 

3,  If  more  than  one  user  can  Goncurrently  operate  a given  process 
(program  or  subroutine),  code  all  module  and  submodule  linkages  involved 
so  as  to  etiable  reentrant  use.  Make  provision  for  each  caller  to  have  his 
own  (protected,  if  possible)  separate  data  workspace  for  data  accessed  by 
the  process^ 

4,  If  reentrant  code  is  being  written,  get  the  reentrant  mechanism 
working  before  coding  any  of  the  design  of  the  reentrant  elements, 

5*  Code  the  procedural  design,  then,  from  the  top  down  in  testable 
phases.  That  is,  conform  coding  to  match  developmenit  testing  phases. 

6.  Code  stiibs  for  real-time  checkout  that  consume  the  proper  durations^ 
as  well  as  recording  trace  information  for  correotness  assessment 


13.3  RULES  FOR  DOCUMENTING  STRUCTURED  CODE 


The  rules  for  doGumenting  the  program  code  are  formulated  so  as  to 
make  the  code  a readable  extension  of  the  programining  specification.  The 
rules  are  not  in  the  direction  of  self-documentation^  but  just  the  opposite! 
The  top-down  development  process  has  gone  to  a lot  of  pains  to  mal^  sure 
that  program  specifications,  such  as  narrative  and  flowcharts  (or 
equivalent),  provide  all  the  information  needed  to  understand  the  program, 
without  references  to  code  listings.  Having  listings  readable  by  themselves 
negates  the  life-cycle  value  of  the  SSD;  the  code  becomes  the  maintenance- 
analysis  hiedium^  rather  than  the  SSD.  Changes  to  the  code  donT  always  get 
inserted  back  in  the  design  documentation  when  this  ha.ppens.  As  a result, 
the  SSD  is  soon  out  of  date,  a worthless,  expensive  document. 


Sec.  J3.31  Documenting  Structured  Code 


95 


t 


I 


t 

I 

t 


Such  a philosGrihy  as  outlined  by  the  rules  that  follow  is  necessary  to 
avert  the  possibility  that  a program  can  be  maintained  only  at  the  code 
level.  It,  moreover,  encourages  the  use  of  computer-ibased  media  for 
holding  and  displaying  both  design  specifications  and  the  code,  Tn  Chapter 
17,  r shall  give  a special  interpretation  of  these  rules  so  as  to  keep 
flowchart,  narrative,  code,  and  annotations  all  together  in  one  source, 

1,  Enter  into  a special,  easily  located  part  of  the  program  documentation 
all  general  program-wide  coding  conventions  and  standards  that  relate  how 
flowchart  specifications  are  coded  Make  the  set  of  conventions  complete 
enough  so  that,  except  for  special  cases  covered  in  the  next  mlOi  they  are 
sUflicient  for  a reader  to  assess  that  the  code  is  a true  translation  of  the 
program  specifiGations. 

2,  Annotate  the  code  corresponding  to  flowchart  specifiGatiDiis  with  any 
special  supporting  information  needed  to  understand  how  those  specifica- 
tions have  been  impleitiented  into  code.  Such  annotations  explain  each 
instance  where  an  unusual  or  non-standard  feature  of  the  programming 
language  is  used  and  is  material  to  aseertaihihg  coding  correctness. 

For  example,  the  FORTRAN  stateinenit  assigns  to 

an  integer  v-'riable,  I,  the  integer  part  of  the  division  of  the 
integer  N by  2.  If  it  is  possible  for  N to  be  odd*  and  if 
program  correctness  acutally  depends  on  the  implied  . 
(automatic)  truncation,  then  the  statement  should  be  so 
annotated  As  another  example,  the  MBASIC'*’^^  statement 
“copy  ' LlNKFiLE ' ’’  clears  the  current  program  workspace 
(but  retains  values  assigned  to  variables),  loads  the  program 
in  the  file  named  ^ linkfile  ^ and  returns  the  MBASIC™ 
processor  to  the  command  mode.  If,  however,  the  copied 
file  contains  a statement  *‘qo  TO  linkstart**  (where  tinkstari: 
is  a statement  number  in  the  ’ LINKFILE'  program),  then 
there  is  an  automatic  run^initiation  of  the  linked  program 
that  is  not  visible  to  one  reading  the  program  in  which  the 
COPY  statement  appears.  In  such  e^esy  the  copy  statement 
should  be  annotated  so  as  to  inform  the  reader  that  the 
Gurrent  program  will  be  terminated  and  cleared  from 
workspace,  that  the  copied  program  will  be  executed 
immediately  after  the  COPY,  uiid  that  any  code  subsequent 
to  the  GQPY  command  in  the  current  program  will  be 
ignored, 

3,  Do  not  repeat  information  appearing  in  the  software  specification. 
Instead  K such  information  is  necessary  to  understand  the  coding,  give  a 
reference  to  the  proper  point  in  the  specification.  This  practice  makes  the 
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code  readability  rely  on  the  program  speGification  and  avoids  dupliGation  of 
documentation, 

4,  ConCorm  annotations,  whenever  possible,  to  make  use  of  any 
automatic  program-ehceking  facilities  available,  such  as  automatic 
flowcharting,  automatic  annotation,  controHogie  verification,  and  statisti- 
cal testing, 

5,  Annotate  source-language  code  listings  to  facilitate  subprogram  and 
siibroutinc  identification,  teferenee,  and  change  control.  Specifically, 
annotate  the  code  for  each  striped  module  with  a header  containing  its 
subprogram  or  subroutine  name,  its  Dcvvey-decimal  number,  initials  (or 
names)  and  dates  of  coding,  peer  concurrence,  and  testing,  all  in  a 
consistent,  uniform  way. 

6.  Identify  steps  within  modules  by  annotations  that  supply  the  same 
identifying  numbers  as  they  appear  in  the  design  specification,  t^igure  13-1 
ilhistrates  such  annotation  of  ai»  asseiublydanguage  program  coded  from  a 
flowchart 

7.  If  a eross-refereiiee  number  appears  on  a flowchart  box,  then  supply 
this  mtmber  to  the  boxr-reference  code  in  the  annotation  for  the  code 
corresponding  to  that  box. 


For  example,  within  a flowchart  module  ‘‘RUNi2k/5*’ 

(initial  ization  for  RUN,  chart  #5),  suppose  there  is  a 
flowchart  box  numbered  ‘*1’’  that  calls  a utility  subroutine 
“SETRio**  (SET  up  I/O  for  Run),  which  is  numbered  as  U7. 

Then  the  beginning  line  of  the  code  corresponding  to  the 
“do  setB'Io"  on  the  flowchart  has  the  identifying  annotation 
1 / 07“  (see  Figure  13-4). 

8;  Indicate  the  prograin  stnictured  hierarchy  by  indenting  lines  of  code, 
when  permissible  in  the  programming  language,  to  reflect  the,  levels  of 
nesting  of  structures  within  other  structures. 


9.  Annotate  dummy  stubs  to  be  removed  later.  Use  a special,  standarck 
easily  distinguishable  series  of  symbols  to  identify  such  annotations^  Identify 
any  special  debugging  code  similarly. 


For  example,  suppose  an  MBASIG'*^^  program  hiis  a table, 
TABLE,  to  be  printed  out  in  a test  mode.  Then  a probe 
instniction  might  appear  as  starts  the  comment  field) 

61  PRINT  TABLE  ! TEST  PROBE  * 
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Figure  13-4^  Rbwthart  and  code  listing  for  RUNIZL/5  module  of  MBASIC'^^/1  shown  In 
Figure  13-1,  illustrating  the  use  of  annotations  to  reference  code  to  procedural 

specifications 


10.  If  there  are  codfe^Ievel  assiimptibns  upon  entry  or  exit  from  a module, 
state  these  in  a comment  block  between  the  module  entry  and  the 
beginning  of  its  compiled  statements. 


Examples  of  things  that  might  appear  in  this  section  are 
memoij'  protection  levels  required  (read-only,  write-only), 
reentrant  or  recursive,  legister  contents  and  usage,  etc. 


11.  If  system  utilities  are  used  with  compile  or  run-time  options,  give 
interfacing  data:  names  of  routines,  calling  methods,  parameters  and  their 
meanings,  hinction  or  service  performed,  requirements  for  calling,  etc. 


12.  If  the  data  striictures  defined  in  the  SSD  require  further  hierarchic 
detailing  at  the  code  leveh  then  iasert  such  information  as  annotations 
located  with  the  data  structure,  properly  referenced  to  the  SSD.  Record 
further  hierarchic  detailings  of  other  resource  acce^  requirements  in  a 
similar  maimer. 
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13,  Provide  other  auxiliaiy  documentation  as  may  be  required  to  bridge 
the  design  to  the  code,  such  as: 

a.  Cross -index  lists  chart  to  file  containing  its  coded  form). 

b.  Public  features  used  (e,g,,  as  index  and  system  registers,  buffers,  etc.), 

G.  Glossary  of  special  variables,  compiler  parameters^  flags,  literals,  and 
storage  structures  not  easily  defined  by  name  or  use  context. 

d.  Memory  use  map. 

e.  Timing  diagrams. 

f.  interrupt  handling  procedures  and  relationships. 

g.  File,  table,  and  data-set  descriptions. 

h.  Examples  of  input  and  associated  output. 

i.  Listing  of  special  flags,  pointers,  and  other  indicators,  together  with 
their  usage  (which  routines,  areas  or  time  of  applicability,  etc.). 

],  Commentary  describing  features  of  code  that  link  performance  to 
design  documents. 

k.  Lists  of  error  conditions,  codes  and  messages,  cross-referenced  to  both 
design  charts  and  the  code  itself, 

l.  Restrictions  on  the  use  of  code  that  is  particularly  sensitive  to 
changes  in  the  design  (mainly  in  time  and  memoiy  space,  but  also 
functional  limits  to  subroutines,  etc.). 

m.  Data  usage  (e.g.,  shared  vs.  public  files). 

n.  Hardware  or  software  constraints. 

o.  Use  of  privileged  instructions. 

p.  Procedures  for  compilation,  linkage  ^it,  etc. 


13.4  STANDARD  PRODUCTION  PROCEDURES 

I This  section  contains  a set  of  guidelines  by  which  the  Software 

I Development  Library  monitors  and  aids  the  production  of  the  program 

f during  its  evolution. 

I 1.  Maintain  Godei  at  its  current  state,  in  files  available  to  all  development 

team  members  on  demand  (see  Figure  13^5).  Establish  a read-only  “control 
copy,”  which  includes  only  the  approved  code.  The  control  copy  does  not 
I contain  any  code  that  will  not  be  a part  of  the  final  program. 
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Figure  13-5.  The  Software  Development  Llhraryi  showing  interaction  among  control 
copy,  working  copy,  and  other  hies  with  software  team 
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2.  Support  the  development  coding  of  new  modules  and  developmental 
testing  so  that  such  activities  muy  take  place  only  by  supplementing  and 
updating  the  control  copy  with  the  new  coda  Working  copies  may  also 
contain  duinmy  stubs,  interspersed  statements  to  collect  or  print  trace 
infoiimatioiu  etc.  The  control  copy  may  be  updated  only  iipon  proper 
authorization. 

3.  Maintain  a tjer  chart  or  data  biise  of  the  project-controlled  code  status. 
For  each  module,  supply  name,  number,  dates  of  submission  and  changes, 
and  its  state  of  completion. 

Adopt  a uniform  notational  scheme  for  annotating  the 
chart,  such  us  “S**  for  ‘‘stub/*  “P**  for  “preliminaty/*  "L** 
for  "Ibbkruhead/*  “A**  for  “audited/*  “C**  for  “coneuried/* 

“R**  for  “returned  for  rework/*  and  “***  for  “completed** 

(see  Section  10,5.6  for  an  example). 

4.  Arrange  to  have  modules  within  each  loadable  program  segment  of  the 
control  copy  entered  so  that,  when  listed^  they  appear  in  their  Dewey- 
dbcitnal  order  This  procedure  is  an  aid  in  locating  code  seginents. 

For  example,  suppose  that  program  #1  hi^s  submodules 
1,2,  1.4/S'l  (i.e„  Subroutine  # I appears  in  box  4)^  and  1,7, 

Then  the  listing  order  of  the  program  at  the  coinpletion  of 
coding  tier-1  is 


I 

1,2 
1,7 
• S!l 

If  1,2  and  SI  require  no  expansion^  but  1.7  has  submodules 
1.7.3  and  1.7,5,  then  the  listing  at  the  end  of  the  next  tier 
would  be  in  the  order 


1 

1,2 

1,7 

1,7.3 

1.7,5 

SI 

and  so  on. 

5,  Develop  document,  and  issue  procedures  by  which  team  members  can 
access,  operate,  and  update  the  evolving  program.  Give  speeific  log-on  and 
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Itjg-off  procedures,  as  well  as  procedures  for  accessing  the  readonly  files 
and  building  working  copies. 


64  Maintain  a standard  production  configuration  including  compilers^ 
editors^  and  other  production  software  (Chapter  17)*  as  well  as  manuals, 
operating  procedures,  etc. 


7.  Provide  an  archiving  function  for  test  data,  dummy  stubs,  and  test 
results. 


8.  Create  a file  naming  and  management  policy  for  project  files  to  ensure 
that  program  modules,  data^  and  the  like  do  not  get  confused. 

For  example,  one  could  make  compilable  segments  contain 
only  submodules  of  a common  ancestor  moduie,  and  name 
the  file  by  that  aneeston  If  several  segments  are  merged  for 
testing  purposes,  najne  according  to  the  modules  or  phase 
being  tested,  and  attach  a test-assembly  cede  number,  TAa 
Similarly,  attach  TCri  to  test  code,  Tt>n  to  i ist  data.  In 
each  case,  conform  the  version  numeral  n so  that  the 
assembly,  data,  etc,,  all  agree. 


i 

I 

I 

f 


1 

I 
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The  sfandards  for  coding  set  forth  in  this  chapter  are  somewhat  unusual^ 
in  that  they  emphasize  coding  from  a documented  specification:  once  the 
program  is  coded  and  verified^  the  *'‘as-biiilt"  speeififeation  becomes  the 
paramount  item  fov  later  sustaining  effort.  The  code  cannot  stand  alone*— 
but  conversely,  the  .specification  is  detailed  enough  that  one  can  read  and 
understand  it  without  reference  to  the  code  listings!  The  documentation  is, 
therefore,  of  necessify  current  when  any  changes  are  made;  program 
analysis,  testing,  and  debugging  are  done  primarily  at  the  documentation 
level,  not  at  the  code  levOl. 

I do  not  want  to  ■irply  by  this,  however,  that  specifications  are 
necessarily  going  to  be  kept  apart  from  the  code.  Indeed,  as  I shall  discuss 
in  Chapter  17,  there  is  a way  to  integrate  code  and  specifiGatipns  into  a 
single  medium^  or  program  base,  if  proper  computer  facilities  are  available. 


I 

i- 
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XIV.  DiViLOPMlNT  TESTING 
STANDARDS 


Deveflopment  testing  forms  the  praGtiea;]  basis  for  assessing  program 
eorrectness,  arid,  for  this  reason^  it  could  as  well  be  called  ''Gorreetne^ 
testing,*'  or  ‘Validation/’  More  often^  it  is  jlist  called  “Gheckout.”  These 
tests  are  run  within  the  development  project  as  the  program  evolves  as  a 
reinforcing  measure  to  assure  the  developers  that  the  program,  thus  far, 
actually  performs  as  speGified^  The  guidelines  set  forth  in  this  chapter 
provide  an  organized  diSGipIihe  toward  accelerating  this  checkout  process. 
At  this  point,  let  me  summarize  what  has  been  required  during  the  design 
and  coding  process  for  the  purpose  of  a^essing  program  correctness: 


a,  Contrbblogic  has  been  specified  to  such  a Idvel  that  will  permit  an 
assessment  of  correetness  of  the  program  flow  on  an  individual 
module  basis. 


b^  The  functional  behavior  of  each  module  has  been  specified  to  that 
degree  of  detail  that  Will  permit  an  audit  of  the  subfunctions  of  each 
inoduie  against  its  stated  function,  and  will  also  permit  a correctness 
evaluation  to  bo  made. 
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c.  Each  module  has  been  specified  in  sufficient  detail  to  permit  coding 
without  functional  ambiguity,  as  a unit,  using  lirtkages  to  striped 
modules  or  stubs. 

d.  The  code  is  a faithful  translation  of  the  design  specificatlonsi 

Overall  end-to^end  and  final  aGceptanee  testing  for  deliveiy  is  covered  in 
the  next  chapter  as  a Qualify  Assurance  function. 


14.1  RULES  FOR  SPECIFYING  DEVELOPMENT  TESTS 

i 

i 

The  objective  of  this  section  is  to  set  forth  a set  of  basic  rules  that  will 
increase  confidence  in  program  correctness  by  demonstration  of  its  I 

implemented  featlires.  ; 

i 

1.  Devise  a sequence  of  tests  or  test  policy  to  validate  the  program  at  the 

current  phase  in  accordance  with  the  remaining  rules  of  this  section.  For  ( 

each  test  decide  which  modules  and  program  paths  are  to  be  exercised;  \ 

These  tests  should  thoroughly  exercise  all  error  or  overload  | 

recovery  mechanisms^  It  is  the  role  of  testing  to  verify  that  j 

such  recovery  modes  have  actually  been  provided  for  in  the  I 

design  and  that  they  function  effectively.  j 

> 

I 

2.  Identify  for  each  test  the  set  of  needed  striped  modules  not  yet  coded,  ^ 

and  then  design  dummy  stubs  for  such  modules  for  testing  purposes.  The  ! 

function  of  these  stubs  is  threefold  (Figure  14-i)!  ; 

a.  To  affirm  that  control  flags  (and  their  vaiuesl^  required  by  a | 

submodule  are  actually  available  in  the  proper  form  to  that  | 

submodule.  j 


b.  To  affirm  that  submodules  which  are  specified  to  alter  control  flags 
may  be  simulated  in  a way  sufficient  to  verify  control  correctness  of 
their  parent  module. 

G.  To  provide  dummy  initialtzations  or  translations  of  data  sufficient  to 
verify  the  interfaces  between  all  modules  at  the  current  phase.  An 
"interface  at  the  current  phase**  is  defined  as  the  set  of  all 
assuniptions  that  modules  within  the  current  phase  make  about  eaOh 
other. 

3.  Prepare  tests  for  each  module  added  at  the  current  phase  using  a test 
driver  (the  entire  program  up  to  this  point  may  be  used  and  is  preferredi 
other  things  being  equali).  Such  tests  are  to  check  for  proper  control  by 
providing  simulated  input  data  or  control  flags  sufficient  to  exercise  every 
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(a)  Mtidule  being  tested 


...  and 
set  FLAG 
for. . . 


RPT  set  to 
trueby 
module . , . 


(b)  Stub  tor  FUNGI 

C FUNGI  "N 


FLAG  « ? 


FUNGI 

. . . and 
reset  RPT 
if... 

FU8C3 

, . . and 
reset  RPT 
if... 


Requires 
FLAG  setup 
in  test 

initialization 


Set 

FLAG 

= NOT  F LAG 


(c)  Stubs  for  FWNC2  ahH  FUNC3 
|^UNG2  (or  ^ 


BFT  = ? 

\ false 


Print 
(or  'C^•^ 


(d)  Test  Procedure 

Test  output  with  F L AG  = true 
on  entry:  ABAC 

Test  output  with  F LAG  = false 
onentryt  AGAB 


Increment 
GOUNT  by  1 


eOtINT 

= 2? 


Requires 

eoilNT  = 0 

in  test 

initialization 


RPT  = false 


Figure  14*1 » Testing  each  flowtine  using  dummy  stubs  (pfintput  shows  coding  compfies 
with  Rowchart;  functional  correctness  can  be  based  on  Whether  printout  sequence  and 
odiertiaceiliifpmation  appem  proper  to  camptde  moibite 
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flowline  iii  the  module.  Siieh  tests  must  demonstrate  that  the  module  has 
perfonned  eorrcctly  and  that  the  module  interfaees  within  the  current 
phase  are  consistent . 


4.  U.se  path  monitors,  trace  printing,  and  other  test-code  features  that 
will  provide  visible  (and  savuble)  evidence  of  the  paTtial  program 
correctness  at  the  current  phase. 

For  example,  one  nuiy  specify  that  all  dummy  stubs,  upon 
execution;  print  out  their  module  name,  variables  declared, 
variables  changed,  conditions  checked,  etc.  Also,  special 
execution  counters  can  be  inserted  into  each  fiowline  to 
count  the  number  of  times  each  (lowliuc  is  traversed 
during  a given  test 

5.  Perform  tCvSts  after  the  successful  demonstration  of  Rule  3,  above, 
which  include  extreme-value,  permissible  data;  out-of-range,  noii- 
permissible  data;  and  random  data. 

Design  such  test  data  principaHy  from  the  users  or 
operator  s viewability  of  the  program,  rather  tlian  as  one 
who  is  acquainted  with  tlie  internal  algorithms.  It  is  useful 
to  design  sucli  tests  using  the  user  or  operator  mamials,  in 
whatever  state  they  exist  at  this  point. 

6.  Define  tests  hierarch  ically,  so  that  tests  using  dummy  stubs  can  be 
rerun  later  (in  greater  detail)  when  the  stiihs  arc  replaced. 

For  cxaniple,  if  a given  set  of  data  or  conditions  cause  a 
diimtUy  stub  to  be  invoked  in  a test,  then  similar  sets  of 
data  or  conditions  can  be  added  at  later  phases  to  test  the 
flowlines  within  the  striped  module  replacing  the  stub. 

7.  Seek  the  simplest  and  e:isiest  tests  that  yield  a high  Gonfidetice  in 
program  GGrrectness. 


For  example,  one  may  be  able  to  test  an  indexed  loop  for 
operation  at  k = 1,2,. . .,n  (k  being  the  loop  index)  to 
ascertain  that  the  loop  is  operating  correctly  for  n much 
smaller  than  its  actual  later  value;  based  on  such  testS;  one 
may  theh;  perhaps,  be  able  to  assess  that  the  algorithm  is 
correct  for  a general  vahie  of  n,  up  to  the  actual  valuew 


m 


Sec,  14,3]  AssembUng  and  Pcffomiing  Tests  Ifli? 

14.2  RULES  FOR  DEVELOPING  TESTS  FOR  REAL-TIME 
PROGRAMS 


RoaUime,  couGurrent  processas  are  harder  to  test  than  non-rea‘4ime 
programs  because  of  their  general  asynchronous  nature  However,  the 
following  guidelines  arc  a beginning* 

1 * Identify  the  testable  status  in  each  phase  of  development  and  devise 
methods  either  to  invoke  such  events  in  reabtiine,  or  else  to  simulate  them 
in  parametric  time.  DeRne  tests  tc  embody  these  methods,  each  of  which 
introduces  a miniminn  number  of  untried  things* 

2*  Design  dummy  stubs  for  striped  modules  missing  in  the  current  phase 
that  will  permit  real-time  tests  to  operate*  In  particular,  make  sure  that 
such  stubs  itiaintaiiv  program  consistcaGy  tue.v  repeatability  of  results  in  a 
“practical  sense/’  even  if  there  arc  bugs)* 

3.  Establish  the  ways  processes  can  interact  in  terms  of  tests  that  ean  he 
performed  to  validate  that  interaction;  and  tlien  input  this  test  philosophy 
into  the  program  design  activity* 

4.  Tn  addition  to  tests  that  traverse  each  program  flowline,  develop  tests 
to  exercise  the  program  s response  to  dynamic  conditions  and  to  evaluate 
the  program  s resistance  to  deadlocks,  thrashing,  and  missed  deadlines* 

5.  Develop  tests  that  include  perturbations  in  hardware  couRguration^ 
timings  or  faults*  Such  tests  are,  perhaps,  best  done  by  simulating  the 
hardware  until  consistency  and  correctness  are  veriRed* 

G*  Consider  the  use  of  hardware  simiihifion  to  provide  test  cases  that 
exercise  the  basic  features  and  interactions  of  the  software  and  stress  the 
design  criteria  as  well.  Simulation  is  particularly  effective  in  stressing  the 
software  in  ways  that  are  diflicuk  to  control  on  actual  hardware* 


14.3  RULES  FOR  ASSEMBLING  AND  PERFORMING 


1.  Append  or  merge  dummy  stubs  and  other  test  code  witlr the  “control 
copy“  of  the  program  in  the  SDL  to  form  a scratch-file  program  on  which 
development  tests  are  to  be  nin  (iFigure  14.‘2)*  Do  not  maintain  a separate 
copy  of  the  evolving  program  for  testing  that  could  later  be  “cleaned  up” 
to  become  the  final program* 
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Test 

Linkage 
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tests 


Rgure  14-2.  Assembling  and  mnnlng  tests 
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Assembly 


Execute 
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Output 
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2.  Establish  and  code  linkage-editing  procedures  to  collect  the  control 
copy,  dummy  stubs,  and  other  test  code  into  an  executable  program  for 
each  test  (in  Figure  14-2,  the  test  version  of  the  program  is  denoted  m 
"Test  Assembly";  the  linkage-edit  code  is  identified  as  "Test  Linkage  Edit 
Coder) 


3.  Test  reahttme  progrmns  for  consistency  and  then  ascertain  correctness. 


14.4  RULES  FOR  CODING  TEST  ELEMENTS 


In  coding  stubs  and  other  dummy  test  code,  it  is  worthwhile 
rcinembering  that,  while  this  dummy  code  may  r^pond  test  data  back  to  a 
module  and  its  hierarchic  ancestors,  that  data  is  not  the  actual  data  that  the 
program  will  access  during  Sml  operation.  It  is  data  supplied  to  verify 
logical  control  and  dofa-space  control  functions  only.  Therefore,  testing  a 
module  having  dummy  stubs  succe^  oiily  in  testing  the  control  aspects  of 
that  module  relative  to  any  data  emanating  from  the  stub.  The  data  design 
is  not  completely  verified  until  the  actual  data  structures  are  actually 
accessed  in  their  specified  manner.  Nevertheless,  stub  tests  do  contribute  to 
data  structural  correctness. 


1.  Code  test  stubs  in  accordance  with  any  specifications  for  path 
monitors,  trace  printings  etc.,  as  may  have  beeii  prescribed^ 


2.  Keep  the  dummy  code  simple.  Do  not  tty  to  perform  the  bmeiions  the 
actual  module  must  perform.  Rather,  simulate  the  interface  needed  for  the 
tests  specified  only.  Remember,  stubs  are  discarded  once  the  actual  module 
has  been  coded* 


For  example,  suppose  a module  specific  to  "accept 
commands  from  a terminal,  translate  these  into  the  setthig 
of  a control  flag^  as  specified  in  Table  4.8.T4,  and  return 
this  value  to  the  program”  is  to  be  dummied  It  is  then 
suffictent  for  the  stub  only  to  return  the  values  of  the  flag 
in  some  simple,  test-GpntroIIed  way,  in  order  to  test  the 
effect  of  command  inputs  on  the  remainder  of  the  program 
('Figure  14-3).  The  stub  need  not  recognize  the  input 
commands  themselves. 


3.  Code  stubs  primarily  to  simulate  control  and  data  operations  for  the 
current  test(s).  Do  not  create,  test  for,  nor  alter  data  that  is  outside  the 
scope  of  current  test(s).  That  is,  dp  not  code  irrelevant  actions  into  stubs. 
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(a)  StripGtl  Module  on  flowchart 
under  test 


(b)  Dummy  Stub 


INCOMD 
SetGOWTG 
as  in 
^8;T4 


INGOMD 


Set 

GOUNTT  ^ 


Set 

COUNT =0 
in  Module . * , 
to  initialize  test 


Id)  Table  5i8«T4,  specifies 
CONFIG  settings 

Gonditibns:  T]  I T 


COUNT = 

V ? > 


GONFLG  = 2 


SalGONFLGs  I 5 2 3 


eomLG^z 


GONFLG  = 6 


PRINT 

'INGQMD' 

GONFLd 


Figure  14*X  Simple  example  of  8 dummy  stub  that  merely  sequences  through  control 
flag  (CpNRiG)  values  to  test  control  logic  of  parent  fibwehart 

4.  Code  several  separate,  simpler  tests  rather  than  one  large  test,  if  this 
will  speed  the  total  jbb  of  stub  coding  and  program  testingi 

5*  Insert  trace-monitor  code  in  paths  (other  than  dummy  stubs)  on  an  as- 
needed  basis  for  Gheckout. 

Trace-mcnitor  code  is  code  inserted  into  program  paths  to 
verify  that  the  program  during  execution  went  through  that 
path,  In  some  instances^  it  is  wise  to  ‘ 'breakpomt”  (test 
stop)  a thodiile  at  its  Chtiy  tb  set  appropriate  data  values, 
an4  on  exit,  to  queiy  the  exit  status- 

6,  Perform  tests,  first,  to  prove  that  the  code  matches  the  flpwdhart  (or 
other  procedural  specification);  then,  examine  test  output  to  assess  program 
design  and  operational  correctnesSi 
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Sec.  14,6]  Documenting  Test  Results 

111  some  instances,  due  to  the  great  number  of  dummy 
stubs  which  may  be  present  at  that  time,  it  may  be 
advantageous  to  delay  the  design  or  operational  correctness 
testing  until  a significant  nuniher  of  the  duminy  stubs  have 
been  replaced  by  the  modtUes  they  represent.  Any 
questionable  design  items  noticed  should^  of  course,  he 
marked  for  later  evaluation  in  the  overall  system. 

14.5  RULES  FOR  DOCUMENTING  DEVELOPMENT-TEST 
SPECIFICATIONS 

1.  insert  test  and  dummy  stub  design  guidelines  into  the  SSD  Test 
Specification  section.  This  material  should  include,  for  each  test: 

a.  The  modules  being  tested,  the  phase,  group,  version^  etc. 

b.  The  purpose  of  the  test  (i^e.,  which  external  specifications  are  being 
verified^. 

c.  Test  inputs. 

d;  Teiit  procedures,  policies,  or  guidelines. 

e.  Outputs  to  be  achieved, 

2.  Specify  test  code,  test  data,  and  test  procedures  in  detail  siifiScient  for 
coding  and  testing,  to  the  extent  that  any  test  code  written,  or  any  test  data 
used,  or  any  tests  judged  to  be  in  eomplianee  with  the  specification,  should 
then  yield  the  same  high  eonfidence  in  program  correctness. 

3.  Specify  how  correctness  of  the  modules  under  test  is  to  be  inferred 
from  the  test  output.  For  each  test,  identify  which  functional  spccifiGUtions 
are  being  validated;,  or  give  a nile  for  deteiimining  whidh  hmctidnal 
specifications  will  have  been  validated  based  on  examination  of  the  output. 

14.6  RULES  FOR  DOCUMENTING  TEST  RESULTS 

Development-test  documentation  consists  of  an  evolving  Software  Test 
Report  {see  Appendix  Jl),  which  summarizes  each  test,  the  modules 
Involved,  and  the  results  achieved^  and  locates  the  output  in  the  project 
archives.  The  following  niles  help  organize  this  documentation  for 
completeness  and  readability. 

i.  Write  a simple  description  of  each  of  the  milestone  tests  performed, 
and  iasert  this  in  the  Software  Test  Report;,  Identify  the  modules  in  the 
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current  phase  that  are  being  verified  by  these  tests;  it  is  permissible  to 
designate  complete  design  phases  as  entities,  as  **all  of  phase  3,  plus 
modules. . 

2.  Archive  code  listings  of  each  of  the  modules  being  tested  and  each  of 
the  dummy  stubs.  If  a module  or  dummy  stub  used  in  current  testing  is  the 
same  as  that  used  in  a previous  phase,  it  need  not  be  relisted  If  properly 
referenced^  as  'The  dummy  for  PARSE  is  the  same  as  that  list^  in 
Section. . .of  this  Report/' 

3.  Maintain  a "Development  Test  Directory"  as  part  of  the  production 
*bg  in  the  Project  Notebook,  which  lists  aH  itiajor  modules  and  gives  cross- 
references  into  the  archives  of  tests. 

4.  In  cases  where  test  specifications  or  criteria  are  broadly  stated  report 
how  coitectness  of  the  modules  was  inferred  from  the  test  output.  For  each 
such  development  test,  specify  which  fimctional  specificatjons  are  being 
validat^t  and  the  extent,  if  only  a partial  validation. 

5.  Collect  all  test  output  for  storage  in  the  project  archives.  Arrange  the 
test  output  in  the  archives  so  ^ to  be  locatabb  using  the  development  test 
directoiy. 


6.  Log  in  the  Project  Notebook  and  summarize  in  the  Software  Test 
Report  all  failures,  ambiguities,  incorrect  actions,  etc.,  for  each  test. 

7.  Maintain  a file  of  “Discrepancy  Reports,"  into  which  are  accumulated 
all  of  the  problem  reports  related  to  the  design,  coding,  and  testings  up  to 
the  current  phase. 

Include  in  such  reports  the  category  of  problem,  such:  as 
“control  logic  error/'  “data  extraction  error,"  “undefined 
variable  required/'  “destroyed  variable  needed  by  another 
module,"  etc.  History  of  this  sort  is  needed  to  refine 
standards  and  iinprove  biture  estimates  of  project  activity^ 


14^  RULES  FOR  THE  SOF1WRE  DEVELOPMENT 
LIBRARY 

I.  Establish  a standard  filernaining  and  management  policy  for  test 
assemblies,  test  data  files,  dummy  stub  files,  test  code  files^  scratch  files,  etc. 
(See  Rule  8 of  Section  13.4  for  one  such  example.) 
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2.  Retain  master  copies  and  backups  of  all  file  elements  (except  scratch 
files)  for  the  duration  of  the  projects  Files  may  be  updated,  or  output  on 
tape,  but  not  deleted  except  as  provided  for  In  the  backup  policy.  At  the 
end  of  the  project,  the  entire  contents  of  project  files  may  be  dumped  (to 
tape  or  printout)  for  the  archives,  and  removed  from  the  computer. 

3.  Retain  a copy  of  all  file  and  documentation  updates  in  the  archives.  If 
an  update  was  initiated  by  an  engineering  change  order,  enter  appropriate 
cross-references  into  the  project  change-control  log. 

4.  Maintain  a cumulative  record  of  the  computer  resources  used  to  test 
the  program  for  later  evaluation  of  team  productivity. 

Measure  CPU  time,  number  of  runs,  etc.,  and  enter  these 
figures  into  the  Project  Notebook  The  total  CPU  time  per 
1000  source  card  images  is  one  such  figure  that  can 
characterize  the  project's  usage  of  developmental  support 
resources. 


14.8  DIAGNOSTIC  PROCEDURES 

In  this  section,  I do  not  want  to  give  a full  set  of  diagnostic  techniques^ 
but,  rather,  how  the  tester  should  respond  when  errors  are  detected. 

1.  Do  not  discard  test  data,  test  code,  dummy  stubs^  etc.,  when  errors  are 
found  in  the  program^  Rather,  retain  these  in  order  to  retest  the  program 
when  the  discrepancy  is  removed. 

2.  Submit  Discrepancy  Report  forms  into  the  archives  for  each  failure 
detected,  and  summarize  each  such  difficulty  in  the  Software  Test  Report. 

5,  If  a real-time  program  fails  in  consistency  (non'-repeatable  errors),  first, 
seek  ways  to  make  the  program  at  least  cOiiSistent,  and  then  correct  it 

4.  Make  all  modifications  to  correct  errors  using  standard  software 
maintenance  facilities  for  source  and  object  text.  No  modifications 
(especially  binary  corrections)  should  be  made  while  Gonducting  a speGtfiG 
test  If  a binary  or  other  such  modifications  are  necessary,  then  rerun  the 
tests  after  the  source  program  has  been  updated; 

This  discipline  encourages  more  reliance  upon  testing  os  a 
program  verifiGatioii  aid,  rather  than  as  a design^patching 
tool 
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5.  Determine  the  set  of  conditions  that  result  in  the  error.  Then  submit 
the  program  to  these  conditions  and  monitor  the  execution  as  follows; 

a.  If  there  are  Goncurrent  processes,  monitor  the  interprocess  commuiti- 
cations.  Typically,  this  requires  examination  of  synchronization 
controls  and  significant  parts  of  messages  transmitted  between 
processes.  Such  an  examination  indicates  the  flow  of  control  under 
which  the  error  occurSi 

b.  Establish  the  relevant  types  of  trace  information  for  the  processes  of 
interest  and  trace  the  How  of  control  (and  timing)  within  these 
processes  to  isolate  the  problem  into  narrowing  subsets  of  candidates. 

G*  Once  the  offending  segment  of  code  is  isolated,  examine  the  results  of 
detailed  computations  (register  contents  and  memory  changes,  if 
hecessaty)  to  isolate  the  specific  causes 

Use  simulation  of  hardware  in  concurrent  program  malfunctiohs  to 
examine  such  things  as; 

a.  Whether  a supposed  process  was  executed  or  not. 

b.  Whether  test  results  up  to  u given  point  are  correct. 

c.  The  sources  of  possibly  erroneous  data> 

d.  Whit^h  of  two  or  more  events  occurred  first. 

7.  Seek  abbreviated  or  scaled-dowh  tests  that  are  sufficient  to  Invoke  the 
malfunction  as  a measure  toward  rediieing  costs  and  hardships  of  computer 
usage. 

8,  tf  an  error  seems  to  appear  because  data  is  being  destroyed,  then 
check  the  scoping,  either  by  tests  or  visual  inspeGtion,  of  the  offending 
variables  or  files  to  find  out  w^here  these  items  are  being  misused. 


14.9  SUMMARY 

This  chapter  has  addressed  disciplihes  that  can  be  applied  to  an  evolving 
program  in  order  to  increase  its  probable  correctness  upon  eompletipni  The 
disGiplines  border  on  formal  Quality  Assutaiice  measures,  which  are  the 
subject  of  the  next  chapter.  The  treatment  of  “Standard  QA“  to  follow,  in 
fact,  has  this  discipline  imbedded  within  it,  but  extends  the  concept  of 
‘ -Gorreetness"  and  ‘Testing"'  beyond  the  program  top-down  evolution  to  the 
more  encompassing  concepts  that  are  needed  to  yield  a soimdi  reliable,  and 
welL-dOcumented  piece  of  software^ 
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XV.  QUALITY  ASSURANCE 
STANDARDS 


In  this  c'Kiq)lor  ! sliiUl  discuss  disciplines  in  support  of  software 
dcvclopincnl  which  contribute  to  tlie  quality  of  the  delivered  product.  Iioth 
functh^nal  and  flocmncnlational,  over  and  above  the  nonnivt  precautions 
;fUd  prac:tici^^  for  good  design,  codings  development  testing,  and 
docnincntatiori  timt  have  boon  addressed  in  previous  chapters,  Tlie 
disciplines  in  this  t'ategon^  I call  '‘Standard  Quality  Assurance/'  or,  for 
sitort,  jnsi  ''QA." 

Quality  Assurance  takes  perhaps  us  many  difl'eroiU  definitions  and  roles 
in  software  production  as  there  are  producers  of  quulitv  software.  Tlie 
general  purpose  of  QA  measures,  howtwer,  is  to  tninimi/c  production 
problems  hy  liettcr  planning  and  exercising  better  and  tighter  controls 
during  the  developinoni  of  the  product.  The  agency  that  is  chartered  to 
provide  the  required  control  fuiudions  is  Quality  Assurance,  and  in  any 
developers  relegate  QA  measures  to  an  organization  scpurale  fron^  the 
dc\x'lapmont  team  in  order  to  obtain  unbiased,  dispassionate  confirmai^m 
that  tile  profluet  hits  met  its  requiroinonls  for  tloliverabilily,  Nbvqy 
customers  will  insist  on  inspections  by  their  own  personnel 
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However,  I do  not  want  to  orient  this  chapter  s approach  to  QA  along 
organizational  lines.  I do  not  want  to  picture  QA  as  a task  separate  from 
development,  nor  dp  I want  to  imply  that  it  can  be  wholly  aecomplished  by 
an  agency  integrated  into  the  dtevelopment  team.  Rather,  I would  like  to  set 
forth  functions,  discipUncs,  procedures^  and  philosophies  for  QA  that  can 
be  independent  of  the  orgaiuzational  divisions  of  tabor. 

The  envisioned  situation  is  thisi  A program  and  its  documentation  have 
been  (or  are  in  the  process  of  being)  produced.  At  eventual  points  in  the 
production,  the  developers  have  convinced  themselves  that  a software  unit 
is  ready  for  configtiration-controlled  status,  perhaps  with  liens  toward 
future  capabili^  not  yet  operational,  but  coming.  At  this  point,  the 
customer,  user,  or  operational  organization  seeks  assurances  that  the 
software  Gonfigiiraticn  satisfies  deliveiy  criteria. 

The  role  I cast  for  Standard  Quality  Assurance  is  to  provide  this 
certification.  The  role  of  this  chapter  is  to  make  this  certification 
trustworthy^ 

iai  STANDARD  QA  ACTiyiTtES 


Quality  Assurance  heeds  to  be  both  effective  and  economical,  in  the  sense 
that  the  expenditure  of  effort  and  costs  to  ceiitity  the  product  represent  a 
justifiable  cost  savings  in  the  software  package  life  cycle.  Ideally, 
duplication  of  effort  among  personnel  should  not  be  necessaiy.  Whenever 
there  is  an  area  of  interest  both  to  the  developers  and  to  QA,  the  QA  tusks 
should  he  in  direct  support  of  development  and  not  in  competition;  For 
thi*^  reason,  many  QA  measures  can  be  integrated  into  the  processes  of 
design,  documentation^  coding,  testing,  Gonfiguration  contrOh  discrepancy 
reporting,  and  change  control  In  later  verification  and  ceil^ification  of  the 
entire  package,  the  developers  should  be  in  direct  siippoit  of  QA,  aiid  not 
in  Gditipetition. 

Fortunately,  the  concurrent  design,  coding,  development  testings  and 
documentation  disciplines,  made  feiuilble  by  hierarchiGi  modular,  structured 
programming,  foster  cdnciirrent  QA,  as  well  After  all,  the  whole  method  so 
far  described  is  predicated  upon  achievihg  a high  degree  of  initial  program 
Gorreetness.  Many  of  the  rules  given  in  previous  chapters  arc  QA  measures; 
Therefore,  much  of  the  QA  function  is  already  integrated  into  the 
development  process; 

For  example,  part  of  the  development  cycle  ineludes  peer  corroboration 
of  design^  coding,  and  developmental  testing  as  a means  for  improving 
software  quality  ('in  addition  to  producing  reliable  software  more  quickly); 
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Part  of  the  team  organizational  disGipline  is  based  on  the  presence  of  a 
Software  Development  Library  and  Project  Archives  to  provide  stable 
Gommunicaitons  media  and  developmental  support  to  team  members* 
Audits  necessary  for  QA  also  have  access  to  these  media* 

Besides  the  informal  QA  mcjuiures  within  a project,  however,  there  needs 
to  be  a formah  eiid^to-end  demonstration  of  the  software  qiiality  and  a 
complete  audit  of  the  entire  software  paefcage-^the  executable  program  and 
its  doeumerttation*  These  should  check  conformanGe  to  standards*  design  vs> 
funGtioiial  specifiGations,  code  vs.  design,  test  results  vs*  test  specifications, 
performance  vs*  requirements*  etc.  Final  Gertificatioii  is  the  verification  seal 
for  delivery. 

The  areas  within  which  QA  can  funGtion  are  |l2j: 
a*  PartiGipation  in  design  reviews, 
b.  Review  of  doeumentation*  listings,  ete* 

G,  Standards  enforeement. 

d;  Configuration  eGntrol.  \ 

e*  Discrepancy  reporting. 

f.  Change  control. 

g,  Testing  and  test  review* 

An  auxiliary  aGtivity  |133  falling  iinito  the  QA  area  is  the  gathering  and 
dissemination  of  statistiGal  data  relating  to  coding*  testing*  later 
maintenanGe,  etc*,  with  respect  to  reliability  and  performance  measures 
Gollectcd  over  many  projects*  Such  data  increases  the  understanding  of  the 
mechanisms  by  which  software  and  softvvare  projects  fail,  ealibrates  the 
amounts  and  types  of  testing  needed  to  achieve  a given  reliability,  and 
monitors  the  differential  utility  of  testing  and  QA  measures  as  programs 
increase  in  reliability. 


15.2  QA  MEASURES  DURING  PROGRAM 
DEVELOPMENT 

Although  usually  not  made  a formal  part  of  the  certifiGation  role  of  QA, 
perhaps  one  of  the  greatest  Gontributors  to  software  quality  is  the  use  of 
peer  corroboration  during  each  phase  of  the  program  development.  Such 
Gorrohoration  is  a QA  mechanism  because  it  promotes  GommumGation 
within  the  design  group*  tends  to  create  and  enforce  standards,  and 
chGonrages  proper  doeumentation  and  reGords. 
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Moreover,  it  is  just  plain,  everyday,  good  engineering  praetiGe,  As  in  all 
good  engineering  practices,  a design  should  be  verified.  Design  verification^ 
as  I mean  it  here,  is  a careful  examination  of  the  design  by  someone  skilled 
in  design,  other  than  the  designer  himselt  Perhaps  the  best  choice  for  this 
job  is  the  designer  s supervisor!  at  the  least,  it  should  be  a senior  colleague 
The  purpose  is  to  get  a coneurrence  that  the  design  at  the  current  level  is 
correct  vi.e.,  that  it  will  do  what  it  is  supposed  to  do)  and  is  “good”  by 
whatever  criteria  have  been  established  for  the  project 

Another  contributor  to  qualiiy  software  is  the  availability  of  malfunction 
statistics  within  a project  and  across  many  similar  projects.  These  statistics, 
plus  a gqdd  set  of  standards^  can  drastically  reduce  the  ‘learning  curve”  by 
indicating  where  projects  typically  get  into  trouble.  Then,  extra  care, 
contingency  plannings  and  similar  measures  can  be  applied  as  the  cases 
warrant. 

The  availability  of  such  statistics  means  that  records  need  to  be  kept  of 
the  numbers  and  kinds  of  difficulties  encountered,  the  time-distribution  of 
such  occurrences  (to  show  when  preventive  measures  will  likely  be  heeded), 
and  the  seriousness  of  faults.  The  Project  Notebook  is  an  ideal  location  for 
such  statistics  during  the  project  development  phases;  a summaiy  repoit  at 
the  end  of  development  can  then  be  incGiporated  into  orgahizatibn  {dr 
industry)  statistics. 

T have  already  given  rules  which  include  these  QA  measures  in  previous 
chapters,  so  they  warrant  no  repetition  here. 


i 

I 


15.3  SOFTWARE  TESTING  CHARACTERISTICS 


DijkstFa's  remark  at  the  1969  NATO  Software  Engineering  eonference 
[14]  to  the  effect  that  “testing  only  proves  the  existence,  rather  than  the 
absence,  of  bugs”  is  a widely  quot^  truth  about  the  nature  of  a necessaiy 
process  in  software  production.  Frankly,  however,  the  prospects  for 
program  reliability  are  hot  as  bleak  as  that  statement  may  make  them  seem. 
For  one  thing,  we  have  seen  in  Chapter  9 that  our  confidence  in  statements 
of  the  form  ‘“"there  are  no  more  errors  In  the  program”  can  be  raised  to  any 
desired  level  by  enough  testing.  The  works  of  Wolverton  and  Schick  [15], 
Musa  [16],  imd  Jelihski  and  Moranda  [17];  which  I will  say  more  about  here, 
reveal  much  about  the  mean  times  between  discoveries  of  software 
anpmaHes  via  testing  (and  usage). 

It  is  important  for  programmers  and  mahagefs  alike  to  understand  just 
what  it  is  that  testing  does  and  does  hot  dp,  how  much  it  costs,  hpw  long  it 
takes,  and  what  things  can  and  cannot  be  inferr^  bom  test  results, 
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Almost  every  software  project  seems  to  enter  a phase  where  it  is  *'90% 
completer  in  whicli  it  appears  to  rcimun  for  a vei^^  dispropoFtipnate  len^h 
of  time*  Much  of  this  tiiiie,  as  it  turns  out,  is  spent  discovering  and 
repairing  anomalies  in  the  program,  operations  manuals,  or  program 
requirements.  The  numbers  and  binds  of  anomalies  in  a software  package 
are  matters  of  fttci  and  not  matters  of  probabilit)';  however,  since  only  a 
relatively  small  portion  of  a large  program's  documentation  and  response 
ean  ever  be  verified  in  a practical  sense,  the  process  of  discovering 
anomalies  appears  to  he  a random  process. 


Repairing  ah  anomaly  requires  study*  software  alteration^  and^  then, 
rcvcrification*  Because  the  differing  kinds  of  anomalies  exhibit  a range  of 
difficulty,  and  liccaiise  human  interaction  is  always  required,  the  repair  rate 
also  appears  to  Im  a random  quantity* 

Statistical  models  of  discover)^  and  repair  provide  us  with  a basis  for 
extrapolating  pa*st  performance  characteristics  into  the  future,  as  a means 
of  predicting  when  testing  will  be  complote,  or  what  the  expected 
Feiiahility  by  a certain  date  will  be*  Siich  information,  if  gained  early 
enough  in  a project,  can  point  put  likely  problem  areas  and  permit  the 
reallocation  of  resources  as  necessary  to  re:dign  completion  datc?>  with 
committed  capabilities. 


15.3*1  A Random  Discovery  Model 

\ The  simple  model  of  anomaly  discovery  used  in  Chapter  9 (viz.,  the 

\ probability  that  an  untried  test  will  find  a new  anomaly  is  assumed 

I proportional  to  the  number  of  anomalies  yet  remaining)  seems  to  apply  to 

[ many  kintls  of  testing,  especially  in  large  systems  with  only  a relatively  few, 

: independent  errors.  This  model  predicts  that  an  ensemible  of  identical 

\ projects  will  find  anomalies  at  a certain  average  rate,  and  that  there  will  be 

i deviations  about  this  mean  of  a certain  magnitude.  The  average  amount  of 

t effort,  here  represented  in  units  of  the  time  applied,  T„,  required  to  detect  n 

I anomalies  is  given  by  the  formula 

i - iti  I 

I 

I 

I The  behavior  of  this  average  is  plotted  in  Figure  154.  The  niean^square 

I,  variance  about  this  average  time  is  similar  in  form. 
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MEAN  NORMALIZED  PIME,  \„T 
u n 

Rgure  15-1*  NomiiaUud  mean  time  to  reach  nth  anomaly 


This  latter  function  is  not  plotted,  but  the  normalized  ratio^  variance  to 
sqiiared^mean  is  graphed  in  Figure  15-2,  Both  of  these  figures  display 
dependencies  upon  n and  the  trlie  number  of  anomalies.  A,  which,  of 
Gonrse,  is  unknown.  The  first  graph  is,  additionally,  a fiinction  of  a testing 
productivity  factor  /3  (it  cancels  out  in  the  ratio).  The  discovery-rate  graph 
is  plotted  for  several  assumed  values  of  A,  but  constant  initial  discovery 
rate,  Xq  — j3A, 


The  ratio,  avg(T^)/avg(T\),  represents  the  average  relative  completion 
status  during  anomaly  discovery.  The  behavior  of  this  ratio  is  shown  in 
Figure  15-3,  It  shows,  for  example^  that  if  there  are  IGO  anomalies,  then 
when  90%  has  been  found,  orily  about  44%  of  the  total  required  effort  has 
been  expended.  It  costs  56%  of  the  testirig  effort  to  find  the  last  10%  of  the 
bugsl  And  this  cost  increases  to  about  70%  if  there  are  1000  anomalies.  A 
clear  reason  why  software  should  have  as  high  a reliability  as  possible  prior 
to  acceptance  tests! 


Discovering  anoinalies  tells  us  two  thing$.v  n,  the  number  found  so  far, 
and  the  efforts  expended  to  discover  each,  denoted  t^j  for  k — 1,.  . ;,n.  The 
maximum-likelihood  est^^^  of  A and  jS  are  values  simultaneously 

satisfying  the  formulas: 


Sut^.  ^5, 
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■As  a r^utt  of  this  modeU  there  are  several  important  Gonclusidns  that 
one  may  draw  about  anomaly  discoveiy*  The  ihfbranation  contained  in  the 
four  figures  presented  so  far  clearly  points  out  the  following  facts: 

After  detecting  n errors,  one  may  estimate  the  total  number  of  errors 
present  in  the  program.  Estimation  accuracy  is  higher  iii  programs 
with  larger  nurnbers  of  errors  to  begin  with  and  then  only  after  a 


h Having  estimated  that  a significaiit  fraction^  say,  90%,  of  the 
anomaUes  has  been  founds  one  may  estimate  (Figure  1^3)  how  much 
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Figure  154*  MeaBurement  ratio  vs  maximum  IJKellhood  estimtfijr  for  number  of 
ancmalled,  given  the  number  n of  anomalies  discovered  eo  far 


effort  Is  yet  required  to  find  the  remaining  16%,  This  remaining  10% 
will  almost  eertaiilly  require  a disproportionate  amount  of  effort  to 
discover.  However^  that  effort  requirement  is  not  unreasonable  or 
unnafurah  It  is  one  of  the  laws  of  software* 


c.  The  variation  in  the  total  effort  that  an  ensemble  of  identical  prpjects 
would  require  to  discover  n anomalies  increases  with  n*  That  is  not 
unusual;  most  random  phenomena  display  increased  variations  when 
the  mean  value  al$o  increases*  However,  percentage  variations  usually 
decrease  as  the  size  of  the  satnple  space  increases.  The  anomaly 
discovery  process,  too,  displays  this  normal  behavior  (Figure  15-2)  up 
until  about  80r^85%  of  the  anomalies  have  been  found.  Then,  the 
effort  required  to  find  the  final  15-20%  of  the  anomalies  can  be 
ejqpected  to  deviate  from  the  expected  time  by  wider  and  wider 
margins,  even  on  a percentage  effort  basis.  If  schedules  are  being  set 
or  forecasts  being  made  requiring  contingencies  or  reapportionmeht 
of  resources/ such  variances  need  to  be  taken  into  account  in  order  to 
avert  schedule  disasters. 


d.  The  above  behavior  supposes  that  a constant  level  of  effort  is  being 
applied  toward  finding  anomalies  using  methods  which  find  these 
errors  as  a purely  random  event.  ThereforCi  these  discovery 
characteristics  will  most  certainly  be  in  effect  udless  some  testing 
methods  can  be  brought  to  bear  which  either  intensifies  the  effort  or 
else  organizes  the  test  cases  in  such  a Vi^ay  that  errors  are  more 
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detemiinistically  found;  (The  tests  in  this  and  the  preceding  chapter 
are  directed  specifically  toward  this  latter  end  J 

1S.3i2  An  Anomaly  Repair  Model 

Before  addressing  a more  general  find-and^^fix  model  for  anomaly 
performance,  let  me  first  presume  that  a number  of  anomalies  have  been 
discovered,  that  a constant  effort  (again  measured  in  units  of  time)  is  being 
applied  toward  their  repair,  and  that  the  probabili^  that  the  anomaly 
currently  being  worked  on  can  be  fixed  by  applying  only  an  additional  At 
effort  is  proportional  to  that  effort,  viz,,  juAt  for  some  constant  effort  factor 
U.  Such  presumptions  about  the  repair  process  lead  to  simple  calculations 
for  the  statistics  of  the  required  repair  effort,  for  m anomalies: 

T =avg(T  )=— 

ni  nr  jji 


T“ 

m 


m 


This  model  predicts  that  all  of  the  n known  anomalies  will  be  repaired 
uniformly  in  time  with  growing  absolute,  but  decreasing  relative^ 
uneertaihty.  Each  anomaly  requires  an  average  time  1/fi  to  repair,  and  the 
standard  deviation  from  this  average  is  also  1/^. 


This  model  also  infers  that  once  an  anomaly  is  discovered  its  repair  is  a 
fairly  well-ordered  process^  The  repair  rate  statistics  do  not  depend  on  the 
total  number  found  so  far,  for  exairiple.  The  characteristics  of  this  model,  in 
fact,  fit  fai%  well  with  observalde  statis^^  in  actual  projectSi  A besNlt 
line  through  observable  data,  then,  is  a measure  of  u* 


Whenever  the  initial  find-rate,  Xq  in  the  preceding  section^  exceeds  the 
constant  fix-rate,  there  will  be  a Gertaih  spaii  of  time  during  which  there 
will  always  be  operi  anomalies:  detected,  but,  as  yet,  unrepaired;  However, 
there  is  an  eventual  time  at  which  the  decreasing  discoveiy  rate  falls  off  to 
the  point  at  which  all  will  have  been  removed.  When  this 

conation  (called  “zero  defects**)  occurs,  the  repair  rate,  of  course,  drops  to 
zero,  and  the  model  tip  longer  applies* 
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The  average  time  to  zero  defects  can  be  estimated  from  the  discovery 
and  repair  modek  and  data  by  extrapolation  (Figure  15-5).  This  will  occur 
roughly  where  the  two  cuive^  cross,  a condition  given  by 


ti- 1 


k"0 


1 

A-  k 


On  reaching  zero  defects,  there  remain  A — n anomalies  yet  to  be  found  As 
it  turns  out,  the  ratio  r = 1 — tn/A),  or  the  fraction  yet  undiscovered  at  the 
time  of  first  zero  defects,  is  a function  principally  of  the  initial  rates  of 
progress,  as  shown  in  Figure  15-6.  AcGording  to  this  figure,  an  initial  find- 
fix  ratio  in  excess  of  about  2,2  will  result  in  fewer  than  10%  lurking 
anomalies  after  zero  defects  have  been  reached. 


15*3.3  Effects  of  Variation  in  Effort 

The  anomaly  models  in  the  previous  section  were  based  on  constant 
levels  of  effort  being  applied  to  finding  and  fixing  of  anomalies.  The 
assumption  of  constant  effort  is  tantamount  to  equating  time 
Gumulative  expended  effort  in  the  equations  and  figures  presented^  In 
actuality,  however^  the  effort  profile  may  be  variable  for  many  reasons, 
among  which  are  manpower  phasing,  availability  of  computer  resources, 
and  availability  of  software  resources.  Thus,  the  accumulation  rate  of 
applied  effort  may  diflfer  greatly  from  the  linearly  rising  accumulation  of 
time. 


^ure  15-5.  Plot  of  nontiatized  anomaly  dkebvery  time  for  A = 10D  and  normaUzect 

anomaly  repalrtime  for  Xo^/i  ^ 
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Figure  R/Tean  time  fhterset^idn  approximation  to  tractJan  of  anomalies  remaining  at 
time  of  flmt  2ero*defect  condition 


it  is  typical  that  effort  during  the  early  testing  is  at  a rather  lower  level 
than  later  on,  because  “things  are  getting  up  to  speedi*'  Effort  is  being  put 
into  planning,  coordination,  trainings  and  resdurce  acquisition  rather  than 
into  actual  testing,  Toward  the  end;  effort  may  drop  again,  to  the  level 
supported  by  operations  and  sustaining  personnel  This  phenomenon  is 
illustrated  in  Figure  15-7;  in  this  figure,  1 person  is  applied  for  7 days,  7 for 
25,  4 for  22,  and  2 for  30  days. 
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Figure  1S-;7.  Wdrk*revet  profile  and  eumulattve  effort  normalized  by  Initial  discovery  rate 
of  Ao  B 2 anomaliesiper  man-day 


Compensation  for  vaiying  levels  of  effort  (at  the  same  produetivity  levet^ 
is  acconi^Ushed  by  replacing  the  time  variable  in  figures  and  fbrmUli^  by 
the  accumulated  hours  of  work  up  to  that  point  An  illustration  of  this 
principle  appears  in  Figure 


Conversely,  one  may  compensate  in  reverse:  That  is,  the  anemaly-versus- 
efibrt  behavior  may  be  plotted  and  analyzed  using  the  previous  estimators, 
then  translated  via  the  prqji^ted  wbrMevel  profile  into  estimates  of 
anomaly  status  at  future  dates. 


riME,  days 


Figure  15^  Effect  of  work-level  profile  on  discoyeiy  of  onomalles  for  Figure  15-7  and 
^ 2 anomaUos  per  man-day 
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When  work  levels  changCi  the  productivify  factors  are  also  apt  to  change 
merely  because  a different  set  of  individuals  are  performing  the  tasks.  If 
work  levels  remain  constant  for  long  enough  periods  of  tune«  the  relative 
productivity  per  individual  can  be  estimated  and  also  factored  into 
calculations.  An  example  of  such  re-evaluatiohs  of  productivity  is  given  in 
the  next  section. 


15.3.4  Cascaded  Testing 

Even  when  work  profile  effects  are  factored  in,  it  is  frequently  the  case 
that  discovery  of  anomalies  takes  place  in  various  environments  for 
supposed  econoinic  reasons.  Certain  anomalies  may,  therefore,  not  be 
discoverable  in  one  environment  but,  perhaps,  discoverable  in  another,  due 
to  different  software  hardware  configurations. 

For  example,^  if  a set  of  reahtime  programs  are  first  tested  outside  the 
reahtime  environment,  those  anomalies  that  are  due  to  the  realrtime 
interaction  among  processes  are^  perhaps,  not  discoverable  by  any  means 
until  the  programs  are  integrated  into  their  tnie  operational  eiiviroiuneht. 

In  such  cases,  only  a lesser  number,  say,  A^,  of  the  total  anomalies  will  be 
findable  during  the  first  phase  of  testing,  no  matter  how  long  carried  foith. 
If  the  second  phase  takes  place  in  the  final  operations  environment  and 
begins  after  n anomalies  in  the  first  environment  are  found,  then  A — n 
become  discoverable  during  this  stages 

This  phenomenon  is  iHiistrated  in  Figure  15-9j  which  assumes  a constant 
level  of  effort  A = 100  total  anomalies,  and  Ai  = 50  findable  during  the 
first  phase.  Switching  to  the  operational  environment  takes  place  at  45 
errors^  or  90%  of  those  that  can  be  found  in  that  environment.  As  may  be 
seen,  multi-stage  testing  may  take  a sighificantly  longer  time  (31%  in  the 
illustrated  case;  to  find  all  anomalies. 

Moreover,  the  test  time  requirements  on  usage  of  the  operational  facility 
are  about  the  same  (52  vs.  46  days)  in  either  case.  Thus,  an  expenditure  of 
16  days  saved  6 days  in  the  pperational  facility.  Actual  dbllar  costs  for  such 
situations  need  to  be  determined  in  order  to  justify  multi-stage  testing  when 
it  can  be  avoided.  Unless  there  are  other  overriding  constraints  that 
mandate  multi-stage  testing,  this  form  of  “bottom-up”  anomaly  discovery 
plan  is  likely  not  to  be  cost-  and  schedulereffective. 

Figure  15-10  is  an  actual  anomaly  histoiy;  t mfoitimately,  the  work  profile 
and  productivity  information  was  not  available  so  that  a more  detailed 
Gomparison  with  the  theoretical  models  was  not  possible.  However,  the 
reader  may  note  that  all  of  the  predicted  elements  are  present:  The  effects 
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Figure  15*^^  Gaseaded  dls^very  of  1G0  anomalioa  in  2 stages  where  SO  anomalies  only 
were  visible  during  first  stage  for  same  0 » 0^1 


of  low-lcvel  effort  during  the  start  of  testings  the  decreiisuig  rate  of  anonialy 
discovery  in  the  snb>opcratiGnal  environment,  the  iitereiising  rate  thereafter 
in  the  operational  environmeitt,  and  the  ultimate  leveling  off  as  testing 
continued^  The  figure  Indicates  the  relative  levels  of  efforts  needed  to  make 
the  plotted  curve  best  fit  the  measured  points  (crosses)»  The  estimated  final 
number  of  anomalies  wtis  about  306,  but  only  about  218  were  findabic 
prior  to  operational  transfer. 


tSA  RULES  FOR  ACCEPTANCE  TESTING  AND 
CERTIFICATION 


The  ultimate  goal  of  a software  package  is  that  it  operates  error-free  and 
meets  operational  requirements*  The  proof  that  it  performs  as  it  should  can 
be  accomplished  only  by  adequate  demonstration  and  stringent  testing.  The 
following  rtiles  do  not  address  organizational  but  funGtional  responsibilities. 


1.  Determine  the  type  and  extent  of  deliverable  items  and  testing  needed 
to  satisfy  the  aeceptance  requirements* 


2.  Develop  and  doeuinent  test  plans  and  procedures  that  define  what  to 
test,  how  and  when  it  is  to  be  tested,  Avhat  to  look  for  during  and  after  the 
running  of  the  tests,  and  what  to  do  with  materials  sitpplied  for  testing. 
Descriptions  of  tests  in  the  Test  Specification  in  the  SSD  should  include 


tt.  Test  objectives  and  procedure.^  to  achieve  those  objectives. 
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ingura  15^10*  AppHcatibn  of  theoretical  ancmaty  discovery  modv^l  to  actual  project 
Invotvtng  about  100;000  lines  of  assembly  language  code 

bi  Equipment  (hardware)  required  to  Support  and  complete  the  test 

c.  Software  required  to  support  the  test 

d»  Limitations  relative  to  the  accomplishment  of  the  test,  such  as 
timings  hiirdware/software  ihteractioUj  etc, 

e.  Methods  to  be  used  to  verify  performance  of  the  software,  such  as 
inspection^  review  of  analytical  data,  visual  displays,  and  analysis  of 
ou^ut 

L Acceptance  criteria  in  terms  of  presence  or  absence  of  specified 
characteristics,  such  as  inputs,  outputs,  limits,  ranges  of  input/outpuL 
amount  of  data,  and  critical  values. 

g.  Test  sequence  or  list  of  ordered  steps  to  be  executed  to  perform  the 
test. 

h.  Initiation  instructions  relative  to  bringing  up  the  systein  into  the  test 
cuiifiguratibu^ 


I 


I 
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i.  Termination  and  restart  contingency  iiistnictionis. 


3*  Schedule  and  perform  tests,  complete  and  end-to-end,  in  accordance 
with  the  test  plan,  hiit  (irst  as  ‘Validation  tests'*  or  “rehearsals**  that  are 
basically  gross  checks  of  the  coding  agaitut  functional  specifications  and 
validations  of  the  test  procedure  docuinciitution.  Encourage  the  develop- 
ment-testing persotmel  to  perforin  these  validations  themselves,  to  attend 
the  rehearsals,  or  to  monitor  and  critique  the  testing  results.  If  anomalies 
noted  during  these  diy  runs  uncover  program  discrepaneics,  advise  tlie 
project  manager  for  appropriate  actiom 


The  SSD  “as  built*’  or  acceptance  readiness  review  freezes 
tlie  configuration  for  deliveiy  te.sts.  All  changes  subsequent 
to  the  freeze  require  formal  anomaly  reporting  and 
archiving  of  red^Iincd  items.  An  anomaly  smninar)'  should 
be  presented  at  the  acceptance  review. 


4,  Asc^eitain  that  the  program  response  meets  its  functional  requirements 
based  on  tests  derived  primarily  from  the  uscr/operator  inannal(s).  If  titning 
is  not  critical,  enable  ilowline-trucc  features  to  gauge  what  percentage  of 
the  actual  instruction  Code  has  been  tested  during  this  functional  testing. 


5.  Ascertain  that  the  program  response  meets  performance  requirements 
(speed,  memory  usage,  etc.)  by  benchmark  tests  derived  primarily  in 
response  to  system  and  onvironmental  requirements,  but  using  tests 
developed  for  functiionai  testing.  That  is,  certify  the  performance 
paranieters  on  the  same  portion  of  the  program  certified  functional l>\ 


G,  Perform  final  aceeptanee  tests  only  in  the  actual  operational 
environment  or  in  an  exact  duplicate  of  the  actual  Otherwise,  attach  a QA 
lien  to  the  eertificafeion  for  later  removal,  after  delivery  and  contingent 
upon  stated  retest  criteria. 


Simulation  in  other  than  the  actual  operational  environ- 
ment is  useful  as  preeursoiy^  testing  cir  perhaps  as  final 
development  testing;  however,  the  testing  on  which 
acceptance  is  biised  should  be  performed  as  stated.  The 
acceptance  test  procedures  should  include  the  generation 
and  loading  of  the  program  to  he  tested  from  flie  deliveiy' 
source  tapes/disks. 


7,  Prescribe  tests  that,  if  successftil  yield  a definable  level  of  confidence 
in  prograin  reliability. 


Test  nil  modes  of  operation,  all  logical  conditions,  and  all 
data  conditions  using  confidence-level  techniques  when 
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they  can  be  applied.  See  Section  9.4  for  one  such 
technique. 

8.  Subject  the  program  to  anomdous  data  (containing  errors,  ouNof- 
range  values,  wrong  data  sets,  etc.),  overload  conditions,  and  improper 
operations  interfaces  (such  as  eonirobsequence  errors)  to  verify  proper 
program  recovery  in  alt  cases. 

9.  If  errors  are  found  during  certification  that  are  due  to  the  user/ 
operator  manuals,  rather  than  the  program,  arrange  to  have  the  manuals 
corrected  before  delivery,  or  else  state  such  errors  as  a lien  against 
certification,  later  to  be  removed; 

10.  Record  all  deviations  from  test  procedures,  impound  all  test  output, 
and  recover  all  test  materials  (that  are  not  part  of  the  deliverable 
Gonfiguration'). 

11.  Classify  all  anomalies  by  priority  or  seriousness  in  standard 
categories,  such  as; 

a;  Removal  of  anomaly  is  critical  for  usage  of  the  software  as  required; 

b.  Anomaly  degrades  peyformance  or  increases  operational  risks. 

e.  Anomaly  does  not  prevent  software  from  being  used  suGcessfully,  but 
it  is  undesirable  in  that  it  requires  user/operator  reorientation  or 
work-around. 


15.5  SOFTWARE  AUDITS 


In  general^  a QA  Software  Audit  [13]  consists  of  a visual  inspection  of 
documents  to  determine  if  they  meet  certain  known  standards  and 
requirements.  An  audit  is  not  intended  to  review  the  conceptual  approach 
to  a solution  of  a problem  or  to  a design.  It  should  simply  provide  definite 
assurance  that  certain  documents  are  in  accordance  with  what  other 
documents  have  presGribed.  When  instances  of  non-conformance  are  found, 
an  audit  report  should  explicitly  detail  the  lOGation  and  type  of  non- 
conformance^ 

if  QA  audits  are  carried  coneiirrently  with  design^  coding,  documental 
tion,  etc.,  such  audits  decrease  the  possibility  of  oversights,  avert 
misconceptions  that  could  result  in  major  rework  or  liens^  prevent  the 
augmentation  or  alteration  of  the  design  unilaterally  at  later  design  stages 
without  proper  approvals,  and  encourage  a uniform,  standardised  design; 
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Let  me  stress  that  the  module  iilgorithm  is  not  a part  of  the 

audit  Rather,  the  auditing  process  is  purely  a *‘bGOlckeepihg”  job, 
something  which  keeps  the  design  '"honest/*  It  can,  and  preferably  should, 
be  done  by  fomeone  other  than  the  producer  himself,  as  I stared  earlier.  If 
performed  by  a peer,  then  the  peer  can  both  audit  and  validate. 


15.5.1  General  Rules  for  QA  Audits 

1.  Prior  to  the  performance  of  an  audit,  make  a checklist  identifying  the 
practices  to  be  used^  the  documentation  segments  to  be  present,  the 
standards  to  be  met,  and  the  problems  to  be  avoided. 

2.  Identify  the  limits  of  the  audit  in  the  current  development  phase,  such 
as  which  modules  are  being  given  what  type  of  audit  (design  vs. 
requirements,  code  vs.  flowcharts,  etc  ji 

3.  Obtain^  for  auditing  purposes,  one  or  more  copies  of  the 
documentation  that  represent  the  product  at  the  current  audit  phase. 

4.  Utilize  personnel  for  QA  who  have  a good  general  understanding  of 
the  project  in  particular  and  a sound  practical  experience  in  QA  techniques. 

5.  Generate  a formal  QA  report  to  the  cognizant  project  manager  for  his 
information  and  actiom 

6;  Do  not  transfer  software  from  development  to  operational  status 
unless  a QA  audit  has  been  made  and  certifies  that  discrepancies  found  have 
been  properly  resolved  (perhaps  by  the  attachment  of  a lien  to  the 
certification  stating  temporary  waivers  to  certain  disGrepancies). 

7.  Be  watchful  for  omissions  in  content  or  apparent  contFadictions  that 
may  become  sourees  of  conftision  in  later  work. 

8.  Flag  items  as  discrepant  where  clarity  or  exactness  seems  to  be  needed, 
but  is^not  provided; 

9.  Check  the  format  of  each  doctiment  against  its  prescribed  outline  for 
conformity,  as  well  as  to  catch  omitted  segments. 


TO.  Verify  that  stated  program  interface  specifications  under  audit  niateh 
the  cited  environmental  configuration  descriptions  being  assumed. 

11.  Verify  the  existence  of  all  required  documents,  that  these  have  been 
compieted  to  their  specified  levels,  and  that  the  quality  of  each  is 
acceptable. 
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15i&2  Rules  fer  Audltirq  Software  Specifications 

1*  Affirm  that  eveiy  hinction  in  the  Software  Functional  Specificatibh  is 
traceable  to  a functional  Tequirement,  and^  conversely,  that  every  functional 
requirement  has  been  responded  to  in  the  SFS. 

2,  Affirm  that  every  function  in  the  SFS  appears  either  as  a module  or  is 
imbedded  identifiably  within  some  module  in  the  Programiniirg  SpeeiBca- 
tion  portion  of  the  SSD» 

3,  Audit  flowcharts,  narratives,  mode  diagranis.  data-flow  diagrams,  and 
all  other  forms  of  design  specification  against  stnictural  and  documentation 
standards,  stteh  as  those  given  in  Chapter  12.  Speciflcally,  make  sure  that 
within  procedural  spcciflcations: 

a.  All  decisions  in  each  module  test  eKplicit,  determinable  condition 
flags  either  defined  within  that  miiidule,  passed  to  it  as  ati  argunierit 
(or  globally),  Of  returned  to  it  by  one  of  its  submodules. 

b,  Each  data  stmeture  referenced  within  a module  appears  in  the 
Glossary  and  in  a Data  Structure  Definition  Table  (if  its  description  is 
incomplete  in  the  Glossary), 

G.  All  submodules  of  a given  module  perform  actions  identiiiabie  as 
subfunctions  of  the  stated  functidn  of  the  given  module.  Flag  as 
disGrepant  those  siibfunotipns  that  seem  to  be  missing  or  extra. 

d.  All  horizorttally  striped  modules  have  corresponding  flowcharts  (or 
equivalent)  at  the  next  design  tier,  properly  cross-refereticed  by 
Dew^-decimal  notatioa 

e.  All  verticaUy  striped  modules  have  Gorrcsponding  interface  descrip- 
iions  in  an  appropriate  External  Module  Interface  Description; 

f.  All  flowchart  boxes  (or  equivalent)  which  call  either  external  or 
internal  subroutines  have  their  Dewey^ecimal  number  inserted  in  the 
subroutine  crossr-reference  table. 

g.  Flowcharted  specifications^^  drawn  and  annotated  as  per  Sectipn 
12,7.2.  There  must  be  aGcompanying  narrative,  doGuinented  as  per 
Section  12.7.3,  for  each  flowchart.  Alternative  procedural  specifiGa- 
lions,  such  as  GRISP-PDL.  should  be  dtJGumented  as  per  Section 

■ 12,7:5. 

4,  Keep  a record  of  each  flowchart  {or  equivalent)  audited  by  name, 
Dewey^decimal  identifier  and  version  date.  Assign  discrepancies  to 
categories,  and  give  the  number  of  discrepaneies  found  in  each  categoiy. 
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S*  Affirm  that  reail-time  programs  have  documented  standards  to  provide 
consistency  in  Gonaurrent  programs^  Specifically,  verify  that  methods  are 
addressed  which  treat: 

a.  Arbitration  of  shared  resources. 

b.  Anti-deadlock  measures. 

G.  Thrashing. 

d.  Reec>very  from  deadline  failure. 

15*5.3  Rules  for  Code  Auditing 

1.  Verify  that  any  programming  constraints  or  requirements  set  forth  in 
the  SRDi  SDD,  or  S$t)  are  being  met,  such  as: 

a.  Programming  langiiage{s)  used. 

b.  Use  of  existing  capabilities. 

G.  Compile-unit  modularization, 
d.  Reentrancy  considerations. 


2.  Obtain  and  use  as  an  audit  guide  any  project-peculiar  standards,  such 
as; 

a.  Register  names,  usage  standards. 

b.  Mbdule-to-submodiile  linking  methods. 

c.  SpeGlal  handting  of  certain  design  specifications. 

d.  Definition  of  compiler  parameters,  literals,  internal  program  labels, 
and  special  storage  structures. 

3.  Affirm  that  the  code  "‘matches''  the  design.  In  particular,  verify  that: 

a.  The  code  takes  the  same  modular  form  as  the  design,  except  as 
provided  for  in  special  programming  standards  or  waivers. 

b.  No  functions  have  been  omitted,  nor  have  any  extra  functions  been 
inserted,  except  as  necessaiy  coding  considerations  to  siipppft  the 
given  design. 

c.  Coded  modules  are  properly  crbss-refereneed  to  the  dfesign  and 
annotated  so  as  to  make  clear  that  the  code  does  in  fact  match  the 
design,  box  for  box,  on  the  flowchart  (or  equivalent). 

d.  There  are  no  compiler  diagnbstiGS  or  errors. 

4.  Inspect  the  explanatory  dbcurnentation  provided  in  support  of 
bridging  the  design  to  the  code,  such  as; 

a.  Crossf^referenee  lists  (charts,  or  equivalent,  compile  modules/files')* 
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K Index-register  iisdge  tablf^  dr  stMdai^i 

c.  Glossary  of  special  variables  or  literals  not  in  the  design  and  not 
easily  defined  by  name  or  use  context* 

d*  Meihory  use  map* 

e*  Timing  diagrains. 

f*  Interruptf^handlitig  procedures  and  relationships* 

g.  File,  table,  and  data  set  descriptions^ 

h.  Examples  of  input  and  associated  output* 

I l^isting  of  sp^ial  flags^  pointers  and  other  indicators  together  with 
their  usage  (which  routines,  areas  or  times  of  applicability)* 

j*  Commentaiy  describing  features  of  code  that  link  performance  to 
design  documents* 

k*  Lists  of  error  conditions,  codes,  and  messages,  cross-referenced  to 
both  the  design  charts  and  the  code  itself. 

1.  RestricHons  on  the  use  of  code  that  is  paFticutarly  sensitive  to 
changes  in  design  (‘mainly  time  and  meiiioty  space,  but  also  functional 
limits  to  subroutines,  etc*}* 

ih*  Data  usage,  such  as  shared  public  files  vs*  restricted-access  files* 

n*  Hardware  or  software  constraints* 

O;  Use  of  privileged  instructions. 

5*  Check  that  measures  specified  to  provide  consistency  in  real-tiine  and 
concurrent  programs  are  actually  employed  on  shared  resources  in  the 
prescribed  way. 

6.  Enter  QA  approval  initials  and  date  Into  the  module  headers  of  all 
approved  code  module. 


15^5.4  Rules  for  peve[bpmen$  1%^ 

Having  QA  active  during  the  module  dji^elopinent  testing  is  a measure 
taken  to  shorten  the  time  required  for  acceptanee  testing  and 
For  examplej  if  QA  certifiers  can  see  that  certain  toting  required  for 
acceptance  has  been  peiformed  as  a routine  correctness  measure  during 
development,  then  such  tests  may  not  need  to  be  rerun  for  certificatipn^ 

1.  Asceitain  whether  a given  development  test  $pec|fipatibh  fuM  an 
acceptance  test  cdtenon.  Mark  such  tests  and  obseive  the  results  of  those 
in  partial  fulfillment  of  ceitificatipn 
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In  order  for  a given  development  test  specification  to 
qualify  as  a partial  acceptance  test«  the  development  test 
must  conform  exactly  to  the  (partial)  acceptance  criteria: 
All  functions  will  have  been  demonstrated  as  required,  no 
new  functions  or  efiFects  will  appesu',  and  any  failure  that 
may  mar  the  result  cannot  have  been  the  result  of  a 
software  anomaly. 


2.  Perform  qualified  development  tests  in  partial  fulfillment  of 
acceptance  tests  using  the  exact  same  modules  mid  data  spaces  os  exist  in 
the  final  product  If  any  such  modules  have  been  altered,  or  if  data  storage 
has  been  rearranged,  the  tests  should  be  recertified* 

3*  Audit  the  test  code  and  test  data  used  in  development  tests  that  also 
apply  to  certificatioa  Verify  that  the  test  code  matches  the  test  design,  that 
the  test  data  invokes  the  proper  required  modes  of  operation^  and  that  the 
program  response  echoes  the  requir^  response* 

A Audit  the  software  test  archives  to  verify  that  stated  development  tests 
have  all  been  run,  in  the  prescribed  manner,  and  yield  the  reported  results. 

5.  Summarize  the  results  of  such  development-^supportive  QA  efforts  so 
as  to  show: 

a*  Coverage  of  functional  requirements  verified, 

b*  Error  modes  and  recoveries  demonstrated. 

c.  Timings  as  appropriate. 

d.  Validity  of  results  by  cross-reference  to  archived  tests  or  other 
documentation* 

e.  Signatures  of  test  conductors,  observers,  or  acceptance  personnel 

f.  Names^  Elewey-decitnal  identifier^  and  version  date  of  the  certifii^ 
partial-acceptance  modules. 

15*&5  Rules  for  Acceptance  Test  Audits 

1*  Affirm  that  the  program  and  its  environment  are  under  configuiation 
control,  and  that  the  configuration  being  audited  is  that  which  will  be  (or  is 
being,  or  has  been)  tested* 

2*  Verify  that  test  procedures  exist  in  accordance  with  Acceptance 
Requirements* 

3*  Identify  those  parts  of  the  program  that  have  had  inadequate 
development  testing,  so  that  they  may  properly  receive  more  intensive  tests 
during  certification*  Similarly,  identify  functional  parts  of  the  program  that 


138  Quality  Assurance  Standards 


[CHAP,  15 


have  high  piiiority,  high  reliability^  or  high  impact  on  operational 
requirements,  so  that  they  may  also  receive  more  intensive  testings 

4.  Verify  that  all  required  test  materials,  such  as  object  program  tapes, 
test  data,  eta,  are  eertified  by  QA  and  are  under  configuration  control 
before  acceptance  tests  arc  performed^ 

5.  Verify  that  all  test  equipment  required  to  perform  the  tests  are 
available  and  calibrated  before  acceptance  tests  are  run* 

6.  Verify  the  proper  conduct  of  the  test,  such  as: 

a.  The  test  conductor  has  brought  the  ^stem  up  properly. 

b AU  conditions  of  test  procedures  are  observed, 

G.  Each  step  in  each  test  is  executed  in  sequence  without  exception^, 
using  certified  data  supplied  in  the  Gorrect  sequencei 

me  DOCUMENTATION  OF  QA  ACTIVITIES 

Reporting  and  record  keeping  of  QA  aGtivities  is  an  administrative 
function  that  will  assist  the  QA  activity  itself,  as  well  as  project 
management,  in  tracking  the  progress  of  a software  development  and 
evaluating  its  progress  against  milestones,  Several  kinds  of  reports  are 
useful,  among  which  are  the  configuration  status,  discrepancy  status,  and 
the  change  status. 

Configuration  status  reports  are  the  week-hy-week  summary  reports  of 
the  progress,  in  terms  of  modules  designed  (and  documented),  accepted, 
God^v  and  checked  out,  primarily  for  management  It  also  can  contain  such 
information  as  the  current  version,  last  update  date,  file  name  or  tape 
number,  and  rtatistics,  such  as  core  usage,  etc.  Figure  1541  is  a sample 
report  df  this  type. 

In  larger  projects,  where  the  configuration  evolves  or  changes  noticeably 
from  day  to  day,  there  may  be  the  need  for  more  frequent  and  detailed 
Gommunicatidn  among  the  developers^  in  the  form  of  an  automated  ''Daily 
Software  C>vervievs^,”  Such  a report,  for  example,  may  iriform  its  readers  of 
new  modules  added  or  corrected,  prpbleins  discovered  or  fixed,  the  file 
names  of  current  and  tert  vei^ipns  the  evolving  syrteiii,  newly  created 
tertdOta,  etc. 

A discrepancy  status  report  ia  another  inval^^^  report^  providing 
management  at  predetermined  intervats  with  a summary  of  the  numbers 
and  types  of  problems  being  encountered^  the  rate  of  dlbsiird  of  the  open 
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items,  and  perhaps  the  level  of  effort  in  closing  sudh  discrepancies.  Figure 
15-12  shows  a plot  of  a project  discrepancy  history  that  might  accompany 
such  a report. 

When  engaged  in  a large  and  complex  software  djevelopment,  there  will 
be  many  requests  for  chwges  to  various  modules  dating  the  progrant^s 
evolutionaiy  growth  to  completion^  Since  there  can  be  no  change  to  a 
controlled  so^are  item  without  first  obtaining  an  approval  for  the  change, 
it  is  imperative  that  the  status  of  each  change  request  be  monitored  until  it 
hs«  been  compleled  or  cancelled^  The  change  status  report  is  a summaiy 
report  of  such  activily,  provided  at  predetermined  intervals  to  the  project 
manager.  Figure  15-13  illustrates  the  content  of  an  engineering  change  log 
summary. 


Rgum  15-12.  Anmaly  repoft  Nstory  for  aeoeptanee  te^ng  1973  Peep  Space 
M^brk  Telemetiy/Cpmiitand  Prpce^or  software  aubsystem  (program  was  real-time, 
nbn^stnictured,  developed  by  “classical^  meUibde) 
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Such  r0ports  as  needed  by  the  prdject  whidh  deal  with  software  quality 
are  obtainable  easily  only  if  there  are  conrinuously  current  records  of 
routine  statistics  that  can  be  easily  transcribed  at  any  time.  Such 
information,  as  mentioned  earlier  in  this  chapter,  is  invaluable  for 
estimating  cofsts^  manpov/er,  and  schedules  for  future  projects.  The  Project 
Notebook  is  the  repositdiy  for  such  statistics  as  well  as  the  reports  formed 
from  them. 

Standard  forms  for  change  requests,  change  orders^  change  status,  and  so 
on  should  be  employed  within  a project*  or  across  an  organization*  to 
minimize  the  numiber  of  Irrelevant  decisions  the  suppliers  of  information 
have  to  make.  Figure  15-14  shows  a typical  standardized  sample  form  for 
soliciting  changes.  Sudh  forms  are  accepted  aiid  processed  through  the 
Software  Bevelopment  Libraiy  during  the  development  phase  of  the 
software  life  cycle. 

Formats  can  be  standardized  and  status  reporting  facilitated  by  the  use  of 
eomputerTbased  recording  and  display  of  project  statistics^  Such  techniques 
are  discussed  fuither  in  Chapter  17, 

Besides  the  status  reporting  during  a project,  the  QA  function  is 
lesponsible  for  a final  QA  report,  which  contains  the  program  certification: 
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specifications  meet  requirements,  code  matches  specifications,  and  tests 
verify  that  the  program  runs  without  flaws. 

This  Software  Test  Report  (STR)  is  identified  in  Figure  2-12  as  the 
“Acecptancc  Gertifieatioir*  docunicntatioiL  Figure  15-15  presents  a 
candidate  graphiGiiI  outline  of  the  STR.  in  which  are  shown  suinmniy^ 
reports  of  all  testing  and  audit  aetivitics.  The  first  section  of  the  report  is 
;m  abstract  of  the  QA  findings;  the  second  addresses  plans,  resources, 
support,  and  applicable  Q\  standards  and  conventions  needed  to  read  the 
remaining  material  The  remaining  sections  document  the  findings  of 
testing  and  auditing  the  sofhvarc  to  he  delivered,  A more  detailed  outlitie 
appears  in  Appendix  J, 


15.7  RULES  FOR  SECURITY,  INTEGRITY,  AND 
CONFIGURATION  CONTROL 


When  soft^varc  development  items  arc  produced,  certified,  and  placed 
under  project  control,  they  must  not  again  lie  altered  or  ehanged  in  any  way 
without  proper  approvals,  testing,  docunientutioii.  and  notification  of 
concerned  pcr>sonncl  The  Software  Development  Libraiy-  is  charged  with 
making  eveiy^thing  in  the  software  development  visible  to  ail  concerned, 
while  keeping  the  look  on  approvcci-status  material;  Such  measures,  since 
they  deal  with  program  integrity,  qualify  as  QA  functions.  The  following 
rules  are  gindeUnes  to  promote  program  integrity. 

L Maintain  a master  copy  and  at  least  one  backup  or  reserve  copy  of  all 
approved  material  in  the  SDL.  Retain  the  master  copy  under  the  licst 
physical  security  warranted  by  the  dcvclopnient  circumstuiiGes. 

The  master-copy  materials  should  not  he  used  for  testing 
or  updating,  except  in  gusc.s  of  extreme  emergencies,  and 
then  only  while  in  the  personal  custody  of  personnel 
aiithori/cd  bj^  the  project  manager. 

2.  Make  backup  or  reserve  copies  available  for  testing,  update,  and  other 
devclo])mcnt  activities. 

In  the  event  backup  copies  are  lost  or  destroyetl,  the 
master-copy  Gustodiaii  will  create  roplacements  from  the 
master,  exercising  eveiy  prccautiQn  to  protect  the  master. 

3.  In  the  ease  of  master  copies  of  magnetic  tapes  or  removable  disks, 
then  in  addition  to  the  current  muster,  retain  at  least  the  previous  master 
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and  all  the  update  transactions  in  a foriii  to  recover  the  current  master^ 
should  it  be  lost. 

4.  Keep  all  approved  copy  material  iip  to  date  on  a regular,  workable 
update  schedule. 

15.8  SUMMARY 


Even  if  any  one  project  does  not  specify  or  require  every  procedure 
described  in  this  chapter,  nevertheless,  I have  presented  what  I feel  is  a 
total  and  unified  methodolo^  for  assuring  the  qual%  of  deliver^ 
software.  1 have  tried  to  do  this  by  describing  QA  functions  rather  than  QA 
personnel  or  organizational  assignments. 


I have  tried  to  integrate  QA  into  the  day-to-day  software  development 
acMvitics  to  promote  consistency  between  the  software  requirements  and 
the  delivered  product,  and  to  detect  problem  areas  early  in  the 
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The  word  “documentationj”  as  chiefly  used  in  this  ehapterf  refers 
speoifically  to  information  recorded  during  the  development  of  a software 
system  to  explain  the  pertinent  aspects  of  that  system.  The  entire  histoiy, 
from  requirements  and  program  definition  to  design^  to  coding,  to  checkout 
and  verification,  and^  finally,  to  Gertification^  may  need  to  Le  documented  in 
one  form  or  another.  Included  among  the  items  to  be  so  recorded  are  tlie 
purposes,  methods^  logic,  rationale,  relationships,  capabilities,  and 
limitations  of  the  program  GOmponents.  Also,  pe^aps,  to  be  included  are 
reports  of  manpower  budgets,  schedules,  and  implementation  planning. 
User  doGumeiits,  pliuining  documents,  and  the  others  in  Figure  2-12  are 
further  recordings  of  a program’s  pertinent  aspects  that  must  be  written* 

Obviously,  some  programs  and  projects  will  require  more  or  less 
dbcumentation  than  will  others,  and  the  documentation  that  is  supplied 
may  veiy  well  place  a different  emphasis  in  each  of  a various  number  of 
areas.;  The  level  and  orientation  of  documentation  depends  oii  a nmhber  of 
factors,  which  includes  program  size,  usage,  intended  life  span,  cnticality  of 
^stem  interfaces^  training  of  operators  and  maintenance  personnel  and 
development  team  organization,  to  name  but  a few. 
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The  objective  of  this  chapter  is  to  provide  a uniform  set  of  guidelines  for 
specifying  cotnputer  prograni  levels  of  documentation  to  fiilfill  human 
GommuniGational  needs^  subject  to  econoinic  and  schedule  Gonsideratipm. 
That  is^  the  guiddines  are  aimed  toward  producing  cost-effective,  as  well  as 
usefiih  documentation.  The  types  of  dOGumentation  to  be  produced  and  the 
procedures  for  doing  so  have  been  adequately  discussed  elsewhere  in  this 
text  and  will  not,  therefore,  be  repeated,  except,  perhaps,  by  summaiy, 

16.1  HUMAN  FACTORS 


Documentation  is  for  humans^  to  communicate  what  humans  need  to 
know  in  ord^r  to  interface  in  their  intended  way  with  the  program^ 
Documentation  failitig  to  meet  this  simple  cnterion  results  from  inadequate 
human  engineering.  Problems  involving  documentation,  thus^  should  be 
attacked  as  human  engineering  probiems^  not  as  programming  problems. 

Good  documentation  is  characterized  by  order  and  form,  which  display  a 
clear  plan  or  design  to  whatever  the  writer  wishes  to  communicate.  Clear 
documentation  does  not  fall  into  order  by  mere  chance.  Order  results  from 
carefiil  arrangement  of  suitable  materials  to  fit  a definite  purpose. 


16,1.1  Problems  Caused  by  Inadequate  Documentation 

A 1974  Report  to  the  Gongress  [ISJ  by  the  Comptroller  General  of  the 
United  States  presented  an  analysis  of  over  710  questionnaires  received 
from  Federal  ADP  personnel  and  auditors  from  more  than  70  computer 
installations  throughout  the  United  States,  Europe,  and  Asia,  This  analysis 
showed  that  inadequate  documentation  had  increased  the  cost  of  ADP 
operations,  weakened  management  controls,  contributed  to  the  loss  of 
funds  and  assets,  and  limited  the  potential  for  sharing  computer  programs, 
especiatly  mathematiGal  models. 


The  report  further  cited  inadequate  doGumentat ion  as  being  a significant 
factor  when  programs  had  to  be  rewritten  and  systems  redesigned,  when 
excess  time  was  required  to  make  modifications,  and  when  delays  were 
encountered  in  completing  assignments^  Soitie  of  the  deficienGies  reported 
were:  that  operating  instructions  were  not  siipplied,  or  were  not  clear;  that 
the  mathematical  model  was  not  explained  clearly;  that  sample  runs  were 
absent;  and  that  flowcharts  were  not  supplied^ 

in  addition,  it  was  reported  that  the  lack  of  documentation  made  it 
diffimilt  for  auditors  and  managers  to  review  and  identify  internal  eoritro’s, 
which  then  required  Gonsiderable  expenditure  of  time  from  the  program- 
ming staff  to  e^lain  to  the  auditors  and  managers  how  the  computer 
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system  funetioned.  Lack  of  adequate  documeutatkin  in  many  instances 
prevented  the  appikation  of  programs  to  siluatiom  other  than  those  for 
which  they  were  originally  designed,  but  to  which  they  were  suited^  if 
properly  modified. 

The  net  effect  of  inadequate  documentation,  eonduded  the  report,  was  a 
high  aggregate  cost  that  could  have  been  avoided,  had  proper  documenta- 
tion  been  provided. 

The  causes  of  inadequate  documentation  seemed  to  boil  down  to  two 
lacks:  The  lack  of  standards  and  and  the  lack  of  review  and  enforcement. 
Consistent  preparation  of  adequate  documentation  under  tight  performance 
schedules  requires  good  standards  and  continual  review  to  ensure 
compliance  with  them,  stated  the  report. 

There  was  literally  no  disagreement  among  the  respondents  in  the  study 
that  good  documentation  practices  should  be  maintained  for  all 
programming  projects.  The  problem  seemed  to  be  in  assuring  that  the 
neeessaiy  doeiiinentation  actually  got  done.  There  always  seemed  to  be 
many  competing  tasks  for  the  software  system  implementors'  timej  and 
dGcumpntation  often  took  low  priority— a ehoiee  which  all  too  often  was 
sorely  regretted  later. 

16.1.2  Fulfillment  of  Documentation  Objectives 

Deciding  the  type  of  documentation  and  the  amount  of  detail  needed  in 
each  ciretimstance  cun  be  made  an  easier  task  (than  impossible)  by  setting 
objectives  and  criteria  for  documentation  relative  to  u4io  uses  the 
doeiimentatfon^  what  typo  of  application  they  have,  whether  there  is 
sharing  potential  of  the  program,  how  complex  the  program  iSj  how  often 
the  program  is  expected  to  operate,  how  long  its  expected  lifetime  is,  hoxo 
much  the  documentation  will  cost  in  relation  to  expected  benefits  or 
probable  penalfy  costs,  and  schedule  criticalilip  Some  of  the  objectives  of 
good  documentatiGn  [19]  are  to: 

av  Aid  workers  in  producing  the  program^ 

b.  Aid  managers  in  monitoring  and  managing  produetiGn. 

G.  Enable  and  assist  the  user  to  operate  and  understand  what  is  being 
done. 

d.  Permit  quick  and  effective  modifications  when  needed. 

e.  Form  Cl  basis  for  new  system  planning. 

f.  Assist  QA  functions. 

g.  Increase  sharing  potential. 


150  Levels  of  Documentiation 


[CHAP.  16 


Of  these  objectives,  only  the  first  is  of  direct  interest  to  the  programmer 
and  the  second  is  of  concern  to  his  supervisor.  The  rest  are,  in  large  part, 
downstream  benefits.  Hence,  the  real  monetary  value  of  good  doGiimenta' 
tion  is  also  likely  to  be  downstream.  Much  of  the  documentation  to  be 
supplied  in  fulfillment  of  these  other  ohjeGtives,  however,  is  generally 
required  of  the  developer.  Without  proper  standards,  the  developer  is 
forced  to  guess  what  level,  form^  and  content  the  documentation  for  others 
must  take;  without  proper  incentives,  he  may  not  he  at  all  conscientious 
about  his  guessing;  without  euforeeinertt  of  standards,  he  may,  perhaps 
(inadvertently),  not  he  able  to  respond  adequately  to  the  needs  of  others. 

All  too  often^  we  tend  to  assume  that  anyone  who  can  write  a program  is 
also  capable  of  communicating  to  others  how  that  program  works.  To 
make  this  assumption  a fact  is  a matter  of  professional  training  and 
discipline.  Frogrilin  dpeumehtation  techniques  need  to  he  studied  and 
learned  just  as  diligontly  as  programming  techniques  do.  As  1 discussed  in 
Chapter  10,  each  worker  in  the  development  needs  to  be  capable  of 
describing  his  work  so  that  others  can  read  it,  It's  just  good  engineering 
practice. 

T don't  mean  to  imply  by  this  that  there  isn't  a place  for  professional 
software  documentors  in  a software  development.  There  is.  Perhaps  the 
best  example  of  this  is  the  dDcuinentatitm  for  users  (or  operator)  of  a 
program.  Here,  the  ability  to  communicate  is  paramount;  unless 
insiinictions  are  complete  and  effective,  a program  can  rarely  be  used  to  its 
fullest  capability. 

Moreover,  users  of  a program  have  a right  to  expect  that  the 
documentation  they  see  will  measure  up  to  the  same  professional  quality 
standards  as  the  program  itself. 

I spoke  earlier  of  incentives.  There  is  little  need  for  standards 
enforcement  when  standards  are  viable  and  accepted  by  each  developer  as 
his  own  self-diseipliiie.  However,  programmers  will  supply  most  where 
their  incentives  are  greatest.  If  a low  priority  is  placed  on  documentation, 
or  if  the  documentation  effort  is  given  insufficient  time  or  budget,  or  if  the 
doGuinentation  is  not  regarded  as  highly  as  the  program  itself,  then  the 
motivations  for  quality  documentation  cannot  be  expected  to  even  tie  for 
first  place. 


16.1.3  What  Constitutes  Good  Documeritatidn? 

Documentation  quality  is  charaGterized  by  four  attributes  [20]: 
completeness,  accuracy,  clarity,  and  economy,  tn  the  case  of  program 
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documentation;  these  are  promoted  in  the  team  model  in  Chapter  10  by 
making  required  documetitation  be  the  interfaces  between  dcvclopmeiit 
activities*  The  quality  produced  is  precisely  that  dictated  by  the  activity 
receiving  the  docun)entation»  as  it  must  be  adequate  in  order  for  that 
aetiyity  to  eontimie^  Any  documentation  supplied,  but  unused;  is 
superfluous,  and  could  have  been  omitted;  any  not  supplied,  but  needed,  is 
quickly  apparent,  and  must  he  supplied  before  the  activity  can  continue* 
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Good  documentation  addresses  a need  on  the  part  of  its  intended  readers* 
There  are  several  factors  that  help  match  this  need  to  the  usability  of 
documentation.  Big,  overly  detailed  documents,  for  example,  generally  tend 
not  to  be  used  very  much,  even  though  their  users  may  claim  they  need 
those  reams  of  detail  Size  must  not  be  allowed  to  become  synonymous 
with  complexity. 

The  method  of  presentation  very  often  contributes  to  clarity.  Graphical 
representations  or  displays  and  narrative  descriptions  are  particularly  useful 
in  promoting  understanding,  for  example.  The  proper  narrative  content  and 
the  proper  graphic  to  be  used,  however,  depend  on  the  idea  to  be 
communicated.  For  program  logic,  flowcharts  or  indented  procedure 
descriptions  (such  as  CRTSP-PDL)  are  eflfectCve;  for  routing  of  information, 
one  may  use  data-flow  diagrams;  for  data  structures,  a picture  of  the  data 
layout,  format,  etc.,  can  be  illustrative;  for  reabtime  program  interaGtions^ 
there  are  timing  charts,  Petri  networks,  and  state  diagrams.  All  graphics 
require  accompanying  explanator>^  narrative  to  be  effective.  Other 
candidate  tools  that  foster  communication  are: 

a.  Standard  outlines  for  doGuments. 

b.  Standard  symbols  for  graphics. 

G.  Standaid  format  for  narrative  description^ 

d.  Use  of  cross-references  and  indexes. 

e.  Display  of  documentation  hierarchy. 

f.  Display  of  program  hierarchy  (tier 

g.  Use  of  decision  tables. 

h.  Mighdevel  programming  languages. 

i^  Use  of  itmemonic  descriptors. 

]*  Use  of  Gommerits  in  code  (for  items  uriGovi^red  in  SSD). 

k.  Sample  mn  and  other  examples,  with  ex^ 

I Timing  analyses,  response  plots. 

m.  Schedules,  Pert  Charts,  other  management  graphics. 
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Another  factor  that  governs  qiial%  is  orientation.  Doeumentatibn  for  a 
program  nuist  always  assume  that  the  reader  have  some  prerequisite  Wei 
of  skill.  For  example,  if  a reader  does  not  understand  EngHshv  then  he  is  not 
going  to  understand  a program  document  written  in  English,  and  nobody 
can  blame  the  documentor  for  that  Similarly,  no  one  can  expect  a person 
who  does  not  understand  FORTRAN  to  fully  understand  the  rationale  for 
certain  operations  in  a FORTRAN  progtaniv  Nor  can  one  expect  that  a 
program  to  compute  spacecraft  trajectories  can  be  made  understandable  to 
a person  who  has  not  passed  high-sehool  algebra.  What  one  seeks  in  quality 
doGumentation,  however,  h'  an  imn7ediate  reGognition  of  the  level  of  reader 
required  and  a match  hctweeiv  the  intended  readers  and  those  who  need  the 
documentation. 


A third  factor  is  dOGumentation  in  the  proper  level  of  detail  If  a system 
is  of  any  size,  different  users  will  need  different  degrees  of  detail  in  the 
information  they  extract  The  highest  level  should  be  readable  by  all  and 
tell  the  reader  whether  or  not  the  deeper  levels  are  of  interest  {or  are  even 
readable  by  him).  At  each  level,  there  shoiild  be  a reference  to  the 
dOGumentation  above  and  below  in  depth—that  is,  there  is  a need  for 
documentation  to  be  organized  hierarchically  in  detail  and  Gross-referenced. 


DoGuments  also  need  to  display  this  stmeture  in  a form  that  the  reader 
ean  grasp  and  use  as  a roadmap  toward  finding  the  detail  to  be  extracted.  A 
graphical  table  of  contents  is  often  a ver>'  useful  adjunct,  except  when 
stniGtured  flowcharts  are  being  used;  these  display  the  program  hierarchy 
very‘  naturally,  already. 


Economic  considerations  and  rapidity  of  accommodation  must  be  folded 
into  the  choice  of  the  documentation  media,  DoeiinieatatiGn  published  as  a 
bound  book  will  not  be  flexible  enough  nor  inherently  fast  enough  to 
accommodate  the  SSD  of  a rapidly  evolving  system,  but  may  be  ideal  in  the 
case  of  a widely  used^  stable,  user  manual  for  example.  The  need  for  quick 
answers  to  speGifie  teohnical  qtiestions,  when  there  is  a maze  of 
documentation  that  must  necessarily  exist  for  a dynamically  evolving, 
complex  system,  also  may  tend  to  indicate  that  any  conventional  form  of 
written  documentation  may  be  hieffeGtive.  Automated  dGCiimentation^  on 
the  other  hand,  if  produced  and  kept  current  by  computer  and  viewed  by 
way  of  a suitable  set  of  terminals,  may  help  cope  with  the  situation,  but  the 
extent  to  which  it  cun  be  made  to  contribute  is  limited  by  economie 
tradeoffs  and  user  work  habits.  (A  user  who  does  work  at  home  iii  ofEhours 
will  be  discouraged  from  accessing  doeumentatibn  through  a non^-portable 
terminal,  for  example.) 
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In  summaiy  (Figure  16-l),  for  good  documentation^  the  methods  of 
presentation  should  match  the  concepts  to  be  communicated*  the 
orientation  should  be  toward  the  intended  reader;  the  documentation 
should  be  organized  in  hierarchic  levels  of  detail,  with  an  appropriate 
identification  of  the  required  aptitude  of  the  reader  for  each;  the 
documentation  should  be  organized  in  a form  easily  displayed  or  grasped^ 
to  facilitate  extraction  of  sought-for  detail;  and  the  media  for  docuinenta- 
tion  should  he  chosen  so  as  to  be  readily  available,  updatable  as 
appropriate,  and  conformable  to  the  development  environment.  Such 
documentation  must  be  as  complete,  accurate,  and  lucid  as  end-to-end 
economic  developmental  or  life-cycle  considerations  will  allow. 


dynamic 
Aspects  of 
Program 


Rgure  16-1.  Some  factors  that  influence  the  quality  of  documentation 
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16.1.4  Users  of  Documentation 

Techniical  dGeumeiitatioii  falls  roughly  into  five  categories:  (l)  that  which 
Gstahlishes  the  software  requirement;  (2)  that  which  defines  the  program 
design  guidelines^  program  architecture,  unci  development  reSGurees,  (3j 
that  which  specifies  the  detaili^  program  implementation  and  testing,  (4) 
that  which  instniets  users  and  operators,  and  (5)  that  required  internally 
during  the  development  process.  In  previous  discussions,  f have  focused  on 
one  such  document  in  each  category,  viz.,  the  SRD^  SDD,  SSD,  user 
manuals,  and  the  Project  Notebook  containing  programming  bulletins, 
decision  summaries,  etc. 

Besides  technical  documentation^  howrever,  there  are  management  and 
planning  doemnents  (the  SHD  aiid  SDD  are  ixirgely  of  this  type,  in  addition 
to  their  technical  content).  The  content  of  each  document  produced  iii  an 
effective  software  development  must  be  balanced  between  technical  and 
non-technical  inforn>ation^  based  on  the  needs  of  the  users  of  that 
document 

According  to  the  congressionaJ  report  mentioned  earlier,  99%  of  the 
respondents  indicated  that  they  believed  the  needs  of  the  intended  users 
should  be  paramount  in  making  doeumentation  decisions.  Because  of  the 
various  types  and  levels  of  documentation  needed  across  the  user  spectniin, 
such  judgments  often  require  subjective  assessments  of  benefit 

Users  of  the  program  itself  need  clearly  written,  accurate,  and  meaningful 
descriptions  of  how  to  operate  the  program,  create  input,  and  interpret 
output.  Programmers  need  computer  system  inamials  and  the  technical 
documentation  that  forms  the  evolving  software  specification.  Auditors 
need  doGiimentation  that  cross-references  the  entire  development,  so  that 
they  may  verify  that  that  which  was  required  wtis  specified*  that  which  was 
specified  was  built,  etc.  Quality  Assurance  needs  docuinentatian  in  order  to 
validate  that  deliverables  are  acGeptable.  Tfie  Software  Development 
fiibrar\'  needs  documentation  of  its  configiiration^Gontrol  procedures^ 
anomaly  reportiiig  measures,  etc.,  as  well  as  documentation  of  the  software 
being  produced. 


Project  management  and  programmers  alike  need  docuinentatiGn  in  the 
form  of  status  reports,  policy  overviews,  and  team  bulletins  during  the 
program  development  progress.  Later  readers  of  the  program  will  need  to 
know  what  the  various  parts  of  the  program  do,  and  why;  they  wilt  need  to 
see  the  relationships  among  data  items,  information  flows,  and  storage 
Gonfigiiration  in  graphic  as  well  as  narrative  fonn, 

Modifiers  and  sustaihing  personnel  will  need  maintenance  proeedures; 
such  as  instniGtions  for  updating  a data  base,  installing  a new  version  of  the 
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program  into  the  system,  handting  anomaly  reports^  and  znaklhg  changes 
quickly  and  efleetively. 

Deciding  on  the  type  of  docunientation  and  the  amount  of  detail  needed 
in  each  circumstance  to  satisfy  each  different  of  user  need  is  not  a 
clcar-eut  process.  Nevertheless*  standards  can  be  prescribed  that  will  aid 
development  projects  in  making  rational  decisions  relative  to  such 
questions. 


Many  may  think  that  all  the  niles  1 have  given  in  previous  chapters  for 
meticulously  documenting  each  phase  of  development  constitute  “over- 
kiir *— more  than  any  project  would  ever  want.  Perhaps  so^  Some  may  even 
think  there  is  a need  for  yet  more.  Perhaps  so,  Iii  the  remainder  of  this 
chapter,  I shall  address  some  of  the  factors  that  one  should  consider  in 
determining  what  type  and  how  much  documentation  is  proper  for  a given 
development,  and  I shall  discuss  standard  categories  of  documentation 
levels. 


16.2  DdCUMENtATIdN  STANDARDS 


Documentation  standards  tend  to  coordinate  system  structures  Into  a 
uniform  mold.  Standard  outlines  and  formats,  as  well  as  rtandardized 
vocabulaFies*  necessarily  are  based  on  assumptions  made  about  the  kinds  of 
systems  to  bo  described,  ff  these  assumptions  are  improperly  conceived, 
then  the  organization  of  the  doeumeritation  may  be  poor  for  a partieular 
application,  and  voGabularies  may  have  to  be  stretched  or  misused; 


\^t,  standard  formats  and  vocabularies  allow  the  readers  of  dooumenta- 
tion  to  find  some  piece  of  information  without  needing  to  learn  the 
concepts  and  vocabulary  peculiar  only  to  one  sj^tem  or  program.  Because 
of  this,  such  doGuments  are  easier  to  review,  audit,  and  maintain^  There  Is 
also  less  likelihood  that  designers  and  coders  will  overtook  the  full  impact 
of  statements  or  graphics  contained  within  it.  Thus,  standaids  tend  to 
improve  the  communication  between  all  people  involved. 


To  fulfill  its  goals,  then,  doeumentation  standards  must  be  well- 
conceived^  flexible,  and  designed  so  as  to  make  the  fewest  number  of 
assumptions  relative  to  system-dependent  or  program-dependent  Gonsidera- 
tions.  That  is,  doqjimientation  standards  should  be  made  to  apply  only  to  the 
extent  that  they  are  relevant  to  all  (or  a significant  portion)  of  the  progrmns 
being  developed  with^  an  organization  (if  not  within  a discipline  or  an 
entire  industiy). 
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16.2.1  Standard  Levels  of  DocumentaUon 

In  large,  long-Ufe-cyete  programming  systems,  dbcuihentalioit  must  be 
provided  In  considerable  detail;  however*  for  small*  single-purpose,  or 
*'one-shot"  jobs,  hardly  any  detail  may  be  needed  at  all  In  important  or 
widely  used  applications,  documentation  may  be  typeset  with  professionally 
draft^  artwork;  in  smalt  or  exploratory  programs*  handwritten  text  and 
hand^rawn  sketches  may  be  suffleient. 

In  fcanning  the  document  outlines  contained  in  the  appendices*  the 
reader  may  note  that  there  is  a lot  of  detail  called  for  hi  each.  Every  one  of 
the  topics  included  in  each  of  the  outlines  is  of  potential  concern  to  evety 
program  being  developed^  albeit  many  topics  can  be  dismissed  immediately 
as  invisible  in  the  current  application^  or  not  applicable  to  it*  or  understood 
as  a standard  across  many  similar  situations.  There  will  often  be  additional 
topics  needed  in  the  outlines  for  some  applications. 


Requirements  relative  to  classifibation  of  detail  and  characterization  of 
the  documentation  medium  should  normally  be  settled  prior  to  the 
initiation  of  work.  Such  requirements  are  easily  stated  only  if  there  arc 
wdl^efined,  standard  classifiGations  for  documentation  from  which  to 
choose.  The  specified  classification  then  becomes  the  basis  for  planning, 
directing,  and  controlling  the  documentation  effort. 

The  remainder  of  tSlis  chapter  describes  general  requirements  for 
standard  levels  of  documentation*  and  for  application  of  these  requirements 
to  intended  usages.  These  standards  encourage  the  production  of  only  those 
forms  for  documentation  that  are  needed  and  adequate  for  the  purpose. 

The  k vel  of  documentation  of  a particular  type  needed  by  a given  project 
is  defined  as  the  characterization  of  that  documentation  by  a classification 
of  the  detail  required  and  by  a categorization  of  the  documentation 
medium  and  format  quality.  This  grading  can  be  fitted  to  the  needs  of 
readers  and  to  the  available  development  resources. 

1 shall  first  define  four  classes  of  detail,  ranging  from  “Class  A”  (most 
definitive)  down  to  “Glass  D”  (least  definitive).  The  requirements  for  each 
such  class  are  relaxed  successively  for  each  lower  class  from  A to  D.  I shall 
also,  then^  a little  latefi  define  format-quality  categories  ranging  from 
“Format  1“  (highest)  to  “Format  4“  (lowest).  Guidelines  for  sciecting 
among  each  of  the  classes  and  categories  also  appear  with  each  definition. 

The  spectrum  of  documentation  levels  defines  a lattice  stmeiure  (Figure 
16-2')*  or  a set  of  partial-ordering  relationships  according  to  detail  class  aiid 
format  category.  For  example,  a document  graded  A1  is  both  very  detailed 


See.  16,2\  Dr^otmeniaiion  Standards 


and  beautifully  published;  a document  graded  D4  contains  little  detail  and 
may  be  handwritten. 

Costs  to  produce  documentation  rise  as  the  level  of  detail  increases  and 
also  as  the  format  quality  increases,  and  such  costs  can  be  estimated  or 
measured  with  fair  accuracy.  The  costs  of  not  having  documentation  of  a 
given  are  not  quite  as  easy  to  pin  dowh^  as  these  costs  depend  on 
downstream  life-cycle  utility  factors  that  may  or  may  not  happen  to  occur. 
Nevertheless,  the  agency  that  sets  doGumentation  requirements  must 
carefully  weigh  life-cycle  factors  if  there  is  to  be  a cost-effective 
documentation  plan, 

I must,  therefore^  as:>ume,  in  the  few  guidelines  I give  here,  that  the 
schedule  is  realistic  in  that  it  plans  for  dbeumenting  to  the  selected  Ifeveh 
and  that  suffiGlent  binding  has  been  allbcated  for  doGumerit  generation  and 
distribution.  The  guidelines  that  follow  are  meant  to  help  establish  and 
select  an  appropriate  level  for  documentation  relative  to  other  issues.  The 
principal  factors  other  than  cost  and  schedule  in  selecting  a level  of  needed 
detail  are  the  (l)  assumed  levels  df  skill  of  the  intended  readers,  (2j)  the 
sharing  potential  of  the  program^  (3)  its  expected  lifetime,  (4)  its 
complexity,  (5)  its  use  frequency,  and  (6)  its  generality  of  application, 

I shall  illustrate  the  concept  of  standard  documentation  levels  more 
definitively  Using  the  Software  Specification  Document  as  a ease  in  point. 


DECREASING 
CADEGORIES 
OF  FORMAT 
QUAUTY 

/ 


DEGREASING 
CLASSES  OF 
ETAIL 


TiECHNtCIAN 


TYPESET 


ENGINEER 


high-quality 

■TYPING 


ARGHIllECT 


TYPING 


ORIGINATOR 


HANDWRITING  OR 
LGWr-QUALlTY  TYPING 


Figure  16?2.  pocumentati6n4evel  l^ce  (class  cf  detail  is  graded  A,  B;  G,  end  D;  format 

quality  as  1, 2, 3,  and  4) 
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Suitable  interpretaHous  for  categorizing  otlier  types  of  docuinetitaHon 
(rcqiiircmcnts,  operations,  etc.)  are  then  not  diincult  to  imagine. 


16.2,2  Cl£iss6s  and  Criteria  for  Detail  in  Software  Speclficatloris 


The  classes  defined  in  this  section  signify  criteria  for  the  ainmint  of  detail 
to  be  provided  when  writing  an  SSD.  These  classes  are  consistent  with 
NASA  computer  documentatidn  giiidetines  (21],  but  are  styled  in  the 
manimr  of  JPL  standard  practices  for  engineering  drawings  ! 


16^2.2.1  Class  A Specifications 


Class  A doenmentation  is  the  most  detailed;  it  contains  Sf 
definitions  and  detailed  descriptions  of  ever\'  significant  factor  or  item 
within  the  software  specification,  so  that  the  program  specifications  can  bo 
understood^  impieinentod,  anu  maintained  by  any  teGhnically  qualified 
personnel  (technician  or  equivalent)  without  coiisnltation.  This  class  of 
dncunientation  results  when  the  project  adheres  rigorously  to  the  SSD 
docuincntaHon  rules  of  Chapters  11  and  12.  All  descriptions,  functions,  and 
operations  are  specified  in  that  level  of  detail  which  permits  a eorreetness 
assessment  liy  the  designers  on  an  individua!  module  basis,  and  then  coding 
without  functional  or  algorithmic  antbiguit^^  no  factor  of  an  item  contained 
in  Class  A docuimjntation  is  left  to  the  discretion  of  the  implementor.  All 
operations  within  unstriped  flowchart  symbols  (or  otlier  suitable  specifica- 
tions) are  eovcrcfl  by  appropriate  referenees  to  published  works,  external 
standards  or  internal  conventions,  or  else  are  at  the  programming  language 
level  (sec  Figures  12-15,  12-24,  and  12-25  for  examples). 


Since  the  SSD  is  also  used  as  a maintenance  dGciiineht,  a ClUsSS  A 
specification  coiild  also  he  oriented  merely  to  describe  all  the  pertinent 
aspects  of  the  system,  its  operational  environment,  its  interfaces,  testing, 
and  external  data  bases,  all  to  the  level  of  detail  that  permits  ah 
experienced  maintenance  programmer  to  correct  errors  or  iinplcinent 
authorf  /'^  changes  without  excessive  expenditure  of  time  to  understand  the 
prograul  or  without  the  need  for  consulting  the  program  developers. 


This  class  of  highest  dotuil  is  appropriate  for  SSDs  whenever  the 
intended  readers/users  are  to  be  relatively  unskilled  (technician  level) 
personnel,  and  need  such  detail  to  perform  effectively,  or  where  there  is  a 
need  to  ensure  that  certain  particulars  be  interpreted  in  a specific  way.  In 
some  eascs^  such  as  maintciumce  documentation,  there  may  be  a cost 
advantage  in  lessening  requirements  for  Cliiss  A detail  by  employing 
personnel  with  higher  levels  of  .skill.  However,  sfnec  it  is  not  ahvays 
possible  to  .select  or  predict  the  community  of  readers  or  users,  then  in  such 
cases.  Glass  A detail  may  still  be  appropriate. 
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This  doss  is  also  appropriate  for  SSDs  whenever  a detailed  audit  of  the 
program  is  required,  or  when  the  SSD  is  to  be  used  as  a eontraetual 
instrtunent  with  miuiinul  contract  coordination  and  review.  Other 
indications  for  selecting  this  ehuss  are  (l)  a eritieal  application,  perhaps 
involving  personal  physical  risk;  (2)  good  sharing  potential;  (3)  high 
frequency  of  use;  (4)  highly  intricate  concepts  to  be  communicated;  and  (5) 
long  or  continuing  program  life  cycle. 

This  level  of  detail  probably  finds  its  tnost  applicability  in  user  mannals, 
and  rightly  so:  The  Writer  of  a user  manual  is  generally  unavailable  for 
consultation,  so  the  user  needs  the  extra  detail 

16.2.2*2  Class  B Software  Specifications 

Class  B documentation  requirements  arc  e ssentially  the  same  as  for  Class 
A,  except  that  the  requircnients  for  iteuv  definition  detail  are  somewhat 
relaxed.  Class  B documentation,  however,  is  to  be  suitable  for  conversion  to 
Class  A quality  by  the  addition  of  further  detail,  without  extensive  effort  on 
the  part  of  the  supplier  of  that  detail 

Class  B specifications  define  evoty  factor  of  the  software  item  being 
clcscribed  ic  the  extent  that  qualified  personnel  (engineer  or  equivalent) 
using  documented  techniques  and  approved  prograniining  practices  can 
satisfaetorih'  produce  that  item  entirely  from  inforinaticm  supplied  Some 
specifications  for  coding  of  funGtions,  operations,  data  struetures,  etc.,  irniy 
he  left  to  the  discretion  of  the  implementors  if  these  will  satisfy  program 
requirements  with  respect  to  performance  and  quality  vvithout  unreason- 
able risk  (see  Figure  L6-3  for  an  example).  Assessment  of  control-logic 
correctness  must  be  possible  on  an  inchvidual  inodiile  basis. 

The  level  of  detail  required  for  SSDs  oriented  primarily  toward  program 
maintenance  also  drops,  to  that  amount  needed  by  qualified  inaintenanee 
personnel  to  corrcGt  errors  or  to  implement  changes,  either  after  a minihuil 
consultation  with  the  program  developers  or  after  some  rcasotiabld  review 
and  head^scratehing,  to  discover  how  a specific  part  of  the  program  works. 

Class  B detail  applies  whenever  readers  are  assumed  to  have  itiore  skill 
(engineer  level)  than  that  deemed  appropriate  for  Class  A,  or  arc  othcrwi.se 
capable  of  re.sponding  properly  to  less  detail  The  class  is  also  appropriate 
for  specifications  whenever  the  audit  rcquirctnents  are  for  consistency  only, 
or  wlien  the  .SSD  is  to  be  u.scd  as  a contractual  instniincnt  with  moderate 
vendor  coordination  and  review,  or  with  limited  eontraetual  risk. 

This  class  applies  to  specifications  for  normal  applications  programs  with 
noFtnal  usage,  but  with  limited  sharing  potential  There  may  be  few 
intricate  concepts  to  be  coinmiintcated>  but  there  is  expected  to  be  a long 
or  continuing  need  for  the  pFogFaiti  and  its  doeumentation. 
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SI 


Figure  16-3.  Ah  example  df  a Glass  6 detail  flowchart  (text  within  clouds  Is  not  part  of 
the  flowchart,  but  are  explanations  of  flowchart  conventions;  figure  also  datnohstrates 

Form^  2 quality) 


16,2.2.3  Class  C Specifications 

Class  C documentation  represents  a yet  further  rdaxation  of  require- 
ments for  detail  than  does  Gluss  B.  Glass  C dbeumentation  may  require  a 
considerable  effort  in  rewriting  to  supply  detail  to  meet  Class  A or  B 
Standards.  Glass  G documerttation  of  design  detail  need  only  extend  down  to 
that  ardhitectUral  level  sufficient  for  skilled  programmers  using  hierarchic, 
modular,  structured  programming  practices  to  produce  an  acceptable 
program.  Callouts  for  standard  algorithms,  operations,  etc.,  may  be  used  in 
Class  C specifications;  The  specific  methods  are  left  to  the  discretion  of  the 
programmer,  subject  to  approval  by  the  designers,  and  provided  there  is 
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mitiiinuin  increasG  iii  risk  in  not  satisfying  program  requirements  with 
respect  to  performanee  and  quality  and^  perhaps,  at  a moderate  inerease  in 
debugging  tiine  or  cxploratoiy^  coding  (-Pigiire  16-4).  However,  control-iogie 
correctness  must  still  be  detcrniiiiable  on  an  individual  module  basis. 

Class  C documentation  also  further  reduces*  the  requirements  for  detail 
supplied  to  maintenance  programming*  The  u.se  of  Class  C documentation 
may  require  more  cxtensb^c  consiiltution  with  program  developers*  or  a 
more  extensive  analysis  or  reworking  of  certain  parts  of  the  program  by  the 
maintenance  personnel  to  correct  errors  or  to  make  modifications.  The 
ininiinuiii  doruinciitatiion  required  is  that  necessary  to  set  up  the  program 
source  medium  for  operation  and  modifieatiom  I/O  fortuats,  setup 


SI 


Figure  164.  An  example  of  a Glass  G detail  fiowchart  (corresponds  to  tPe  subprogram 
in  Figure  ld-3;  Format  3 drawing  quality  used  for  IflustraNon) 
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instructions,  and  the  liberal  use  of  comments  in  the  source  listing  (for  items 
not  expflained  in  the  SSD;  however,  redimdanGy  is  allowed  if  ease  of  use  is 
enhanced). 

Class  C should  be  chosen  to  document  programs  at  the  architectural  or 
feasibility  level,  when  there  are  no  formal  requirements  for  QA  or  aiidit  Its 
use  iis  an  SSD  should  be  limited  to  cases  involving  implementation  by 
highly  skilled  personnel  within  the  GOgnizance  of  the  project  mmager;  it 
gouerully  may  not  be  acceptable  or  satisfactory  as  a contractual  instrument 
without  close  coordination  and  review  of  contractor  performance. 

Class  C documentatiori  is  probably  also  advisable  for  uncomplicati^ 
programs  with  anticipated  low  usage,  no  sharing  potentiah  and  short  life 
expectancy.  It  may  also  be  considered  appropriate  for  documents  within 
stable  organizations  having  low  attrition  rates,  or  having  high  levels  of 
expertise  and  experience. 

16.2.2,4  Class  D Speciflcatioiis 

Class  D documentation  is  the  raininud  acceptable  level  of  detail 
advisahie  for  any  program  whose  documentation  is  meant  to  be  retained 
and,  perhaps,  read  by  others  (or  by  the  implementors,  at  a later  time).  Such 
doGiimentation  should  only  be  deemed  acceptable  in  cases  where  no 
upgrading  of  the  documentation  class  is  anticipated^  as  it  may  be  generally 
unfeasible  to  upgrade  the  classification  to  Class  A,  B,  or  C without  a 
concerted  redocuinentation  eflrort.  Standards  for  minimum  detail  are  at  the 
discretion  of  the  preparer  s supervisor. 

Programs  documented  as  Class  D are  suitable  for  maintenance  by  the 
original  implementor  oiily.  A conceptual  example  of  a Glass  D flowchart 
box  appears  In  Figure  16-5. 


Figure  1^5,  THe  FILESOOT  subprogram  reptesented  in  ClaMPd^it(a1doFo 
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l'hi}i  (.^Llss  of  leiivSt  detail  should  be  limited  to  sitnimmy  imitomuh 
o\'er\'iews\  aiul  other  reports  of  minimal  eoinplexity  where  there  is  a need 
to  record  capability,  work  done,  results,  or  what  u program  does  for 
historical  purposes.  Class  D dociimctitation  probably  applies  to  ”oiic-shot'* 
or  single*use  program  SSDs,  or  to  SSDs  for  prognuns  requiring  under  one 
man-month  or  eoj;ting  under  $20i)0  (these  are  not  meant  to  be  equivalent. 


see  m 


Class  D clociiincatatioiv  should  only  Ire  considered  for  speeiiiGations  in 
those  cases  where  the  implementor  is  woU-informed  of  the  function  and  use 
of  the  prognun,  as  well  as  s)»stemi  environment,  and  other  implicattons.  The 
use  of  sndi  Class  D documentation  should  usually  he  restricted  to  use  by 
the  developer  only,  and  may  necessitate  extensive  verbal  contact  with  other 
readers,  or  extensive  time,  revision,  or  rework  (due  to  lack  of 
understanding)  b)'  those,  other  than  the  developer,  who  wish  to  correct 
errors  or  to  make  inodi  (teat ions. 


16.2.3  Categories  and  Criteria  for  Format  Quality  in  Softwam 
Specifications 


The  categories  defined  by  this  section  delineate  format  and  publication 
qiudity  staiidanis  for  documentation  of  an>^  detail  classificatiotu  as  covered 
b)'  Classes  A,  B,  C.  and  D.  Combination  of  class  and  format  spectfieatiAns 
are  coiniucnsuratc  with  NASA  documentation  guidelines  [21]^  hut  are  more 
flexil>le,  as  the  criteria  for  selection  are  herein  made  as  separate, 
independent  issues. 

16^2.3,1  Format  Categoiy  I t Forinal  Puhlieation  Quality 

Format  1 genenilly  applies  to  the  documentation  of  programs  that  arc  of 
suflicient  general  interest,  wide  usage,  or  orgainzationabinuige  value  so  as 
to  be  announced  and  distributed  in  the  highest  publication  quality 
available.  Sneh  documentation  should  be  prepared  in  a fonnai,  rigorous 
maimer,  with  in-depth  technical  review,  meticulous  proofreading,  full 
editing  by  professiptuil  doeiunentation  personnel,  and  organizational 
approval  for  rctea.se  and  distribution. 


In  many  cases,  the  text  of  such  documents  will  be  typeset  and 
pcrinancntly  iiouiid,  or  of  compamiiile  qualit)^;  all  arhvork  will  normally  be 
of  professional  drafting  quality  {23]  equivalent  to  inked  drawings  with  lugh 
qiiality  lettering,  suitable  for  *'textboofc“  illustrations.  The  style  Is  exactly 
that  specified  in  Chapters  H and  12  for  narratives,  flowehartSi  and  other 
descriptions.  Flowcharts  are  further  covered  by  Appendix  B. 


.\iterations  are  distributed  as  errata  if  ininor,  and  as  revisions  by 
reprinting  and  reissue  if  major. 
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Format  1,  or  Formal  Publication  quality,  generally  applifeii  to  eases  where 
the  document  will  find  high  usage,  perhaps  external  to  the  organization, 
where  the  organizational  image  plays  a role,  where  professional 
documentation  personnel  services  are  available  for  formatting,  editing, 
composing,  etc.,  where  u general  and  wide-spread  interest  exists  in  the 
program,  and  where  the  program  is  stable. 


Format  1 dociimeutation  probably  applies  most  often  to  user  manuals, 
announcements  and  summaries,  and,  perhaps,  user-gronp  bulletins.  It  would 
rarely,  1 think,  he  used  for  publication  of  an  SSD,  and  probably  should 
never  be  used  for  an  SHD  or  SDD. 

i6i2,3,2  Format  Category  2:  External  Report  Quality 

Format  2 requirements  are  the  same  its  Format  1,  except  that  the 
requirements  for  editing  and  comppsition  are  somewhat  relaxed.  Format  2 
geuerally  applies  to  the  dOGunrentafeion  of  programs  that  are  expeeted  tq  be 
widely  used  within  an  organization  but  may  also  have  some  outside 
readership  as  well.  Such  documentation  should  be  prepared  with  adequate 
technical  review,  good  proofreading,  editing  sufficient  to  assure  format 
eonsistency  and  clarity  of  expression,  and  r>rganization  approval  for  extomal 
release  and  distribution. 


The  text  of  Format  2 documentation  should  be  of  high  typewritten 
quality  and  suitable  for  oflset  printing,  such  us  that  obtained  using  a 10- 
point  IBM  Executive  Modern  typewriter  font  lUnstratiGns  and  artwork 
should  be  drawn  to  professional  ink-line  drafting  standards  [23]^  perhaps 
with  typed-in  lettering  (see  Figure  16-3).  The  style  is  the  same  as  that 
specified  for  Format  1.  Alterations  to  the  dpemnentation  are  distributed  as 
change  pages,  unless  the  document  is  permanently  bound,  in  which  case, 
changes  are  handled  as  in  Format  1.  Iii  any  ciise,  the  document  is  normally 
enclosed  fay  protective  covers. 


External  Report  (Format  2)  qualify  is  the  normal  level  of  publication 
quaiity  for  doeumentation  that  is  expected  to  find  high  usage,  but  where 
the  aid  of  profossional  dGcumentation  personnel  is  limltedi  where  the 
organizational  image  is  less  sensitive^  where  the  general  interest  in  the 
program  is  less^  and  where  the  program  dGOumentatlon  is  perhaps  slightly 
less  stable  than  one  documented  as  Format  1. 

Format  2 documentation  probably  applies  to  most  of  the  user  manuals, 
anupuheements  and  suinmaries,  and  user-group  bulletins  printed  for  use 
within  an  organization,  or  externally  on  an  interim  basis.  Use  of  Format  2 
for  an  SSD  will  probably  only  be  feasible  for  highly  stable  programs,  or 
those  whose  ai^vork  can  be  computer  draw  and  whose  text  is  contained 
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I und  reproduced  by,  a computer.  Format  2 may  also  be  suitable  for  some 

SRDsaiidSDDs. 

Format  Category  3:  Intcriial  Report  Quality 

Format  3 is  n further  reduction  in  report  quality  from  tluit  required  for 
cither  of  Format  1 or  2,  Format  3 docuinentatiou  generally  applies  to 
speeiiibpurpose  or  in-hpiisc  progran\s  that,  after  careful  eonsideration  of 
the  possible  interest  of  others,  appear  to  have  iusuffideiit  usage,  sharing 
potential,  or  life  expectancy  to  warrant  a higher  quality  format.  Such 
documentatiou  should  be  prepared  with  project  and  QA  review,  tnternal 
rcleitse  and  distribu.:\ion  are  at  the  discretion  of  the  project  manager. 

The  text  of  Format  3 dOGumentatiou  should  he  /ypemnfren,  although 
tliere  need  not  be  any  requirement  placed  on  the  t)rpe\vriter  font.  Arhvorfc 
may  l>e  hand  drawn  (in  pencih  if  reproducible)  using  standard  templates  and 
t^qjcd-iii  lettetiiigv  {See  Figure  16-4  for  an  example.)  This  format  should  at 
least  satisfy  niierofiliumg  standards.  There  is  no  relaxation  on  the  style  of 
narratives  or  illustrations,  however,  from  Formats  1 and  2.  Any 
reproduction  medium  and  binding  suitable  to  the  limited  distribution  is 
permissible.  Covers  are  optional. 

Alteratioas  to  Format  3 documentatiou  are  hatidled  by  distributing 
change  pages  or  errata. 

The  normal  working  level  of  doGUincntation  within  an  org^aiiization  is 
Format  3,  It  is  generally  used  when  the  numbers  of  users  of  the 
documentation  are  liinited,  bift  \yhere  there  is  a need  for  contiiuied  use  or  a 
permanent  record  of  the  recorded  items,  The  documentation  is  usually 
prepared  witliin  the  implementing  organization,  without  the  aid  of 
professioual  documentatiau  personnel,  and  where  there  are  limited  funds  or 
facilities  for  drafting  and  other  artwork.  Tlie  format,  being  less  restrietedv 
can  also  aGcommodate  a somewhat  less  stable  programming  enviromivenh 

Format  3 doGunientation  is  applicable  to  the  working-level  SSD,  SDD^ 
and  SRP,  os  well  us  low-iise  documents  used  for  program  maintenance  and 
operations. 

16.2,3.4  Format  Oitcgory  4:  Minimal  Report  Qiiality 

Forniat  4 is  the  lowest  quality  of  doGumeirtatibn  and  the  least  restricted. 
Review,  QA,  and  distribution  are  at  the  discretion  Of  the  developer(s). 

Format  4 docnuientation  may  be  freehand  (Figure  16-5),  or  may  deviate 
from  style  requiremeuts  and  standai^  practietjs  discussed  elsewhere  in  this 
text  to  whatever  extent  practicaK  at  the  diseretiou  of  the  preparers 
supervisor.  Format  4 documentation  need  only  meet  the  mininuun 
requirements  neces.sary  for  storage  and  retrieval  in  the  SDL.  if  such  facility 
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is  even  used,  {it  is  usually  desirable  to  keep  on  iiie  for  some  period  of  time 
the  documentation  that  results  from  program  deydopment,  such  as  a 
program  abstract,  the  Projeet  Notebobk,  a complied  source  listihg,  test 
cases,  run  examples,  etc,) 

Alteration  methods  are  at  the  discretion  of  the  preparer  or  his  supervisor. 

This  lowest  quality  of  reporting  format,  like  Class  P detaU.  most  often 
applies  to  siuglie  use,  “one-shot’*  jobs  of  cbm^exity,  but 

there  Is  a requirement  to  report  or  record  what  type  of  work  was  being 
produced,  or  what  the  results  of  a given  effort  were/ ahdi  thus,  to  retain 
ccriain  ihformatidn  about  a program  for  historical  purposes.  Format  4, 
thus,  is  suitable  for  exploratbiy,  or  lobMaHba^^  effbi^/ wKeto  there  is  little 
distributlbn  potential,  or  for  programs  requiring  under  one  man-month  of 
eftort,  or  costing  imder  $200&  (these  are  not  ineaht  to  he  equivaient^  see 
|2i]).  Because  of  the  informality  of  the  quality  lestriGtibns,  Format  4 
documentation  can  probably  be  used  better  than  other  formats  when  there 
are  unstable  elements  in  the  system. 

Format  4 documentation  is  generally  not  suitable  for  most  projects 
leading  to  pperatfonul  programs,  or  for  any  forms  of  program  documenta- 
tion,  except,  perhaps,  project  bulletins,  status  reports,  memos,  etc. 

16.3  PREPARA110 

The  procedure  for  documenting  a staruiardized  development  consists  of 
supplying  the  required  in  various  phases,  according  to  rules 

contained  in  the  previous  chapters  of  this  text.  Consistent  preparatfo^ 
adequate  dbeumentatibn  uiider  tight  peiformance  schedtiles  requires 
standards  or  guidclinas  and  continual  review  to  ensure  cpippltaii^ 
those  guidelines.  That  which  is  gbihg  to  be  prodiiced  shoiiid  be  kept  to  the 
minimum  neces^iy  to  meet  the  needs  of  those  whom  the  program  tyill 
impinge,  beeaiisb  of  the  high  costs  of  dbeumenting  software  developments 

164^1  Rules  lor  Project  Management 

Besides  creating  ptogram  doGum  gathering  and  recording  statiis 

information  during  development  is  generally  considered  flQ]  to  be  ^ o of 
the  inost  impbrt^i  project  managem^^  there  ato  no 

hard-^andifast  criteria  universally  considered  to  bp  most  im^^ 
eviduatiitg  the  worth  of  a particular  report  or  ihfoiibati^ 
technique,  Nevertheless^  timelihess^  accuracy,  and  detoitehess  (prbvidfo^^^ 
enough  informatipn  to  identify  the  accomplished  work  unambiguously 
have  always  ranked  high  with  many  managers,  and  certainly  dp  so  with  me. 
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Informal  approuches  to  reporting  status  seem  to  work  best;  written 
reports  should  always  be  kept  to  a minimum.  When  used^  they  should  be 
strictly  constrained  by  length,  time  deadline,  and  very  hard-headed  analysis 
of  their  purpose.  Defining  and  tracking  concrete  events  based  on  ftmctional 
Gapabilities  or  milestones,  os  exemplified  by  WBS  reports  mentioned  in  the 
previous  chapters,  are  particularly  useful  to  higher-level  managers. 


The  following  rules  are  gnidelines  to  aid  project  management  in  selling 
standards  for  documentation  and  reporting  [8]i 


1.  Prepare  a list  of  documentation  lesponsibilitiesi  specifying  the 
individual  responsible  for  preparing,  eoordinaftng,  reviewing,  and  editing 
each  document  from  its  origination  through  its  formal  release  and  updating. 
Keep  this  list  Gurretit,  with  updates  throughout  tlie  life  of  the  project. 


2.  Establish  a docutnentation  plan  as  early  as  possible  in  the  program  life 
cycle.  Identify  the  docuincnts  by  title,  purpose,  and  criteria  for  content  (see 
Section  tft2);  Give  required  or  estimated  initiation  and  completion  dates 
for  each,  and  assign  personnel  through  the  list  in  Rule  1,  above. 


3,  Establish  the  scope  iuid  general  outline  of  the  doemnentation  ploii. 
Address  the  relative  weights  or  priorities  to  be  given  to  technical 
documentation  and  to  management  documentation. 


4.  Set  standards  for  the  formats  to  be  used,  the  time  phasing  to  be 
followed,  and  the  disciplines  to  be  imposed  in  producing  the  documents. 
Then  see  that  these  standards  are  adher^  to  by  adequate  review. 


5.  Accoiuit  for  software  documentation  costs  and  effort  adequately  in 
manpower  profiles  and  scheduling  from  the  outset,  and  verify  tihat  orderly 
documentation  is  heing  carried  on  GonGurremtly  with  design,  coding,  and 
testing  of  the  program^ 


Quantify  the  value  or  benefit  of  documentation  through 
the  probable  costs  that  may  be  required  if  adequate 
documentation  is  not  prepared,  Strike  a balance  between 
documentation  costs  and  axpeeted  usefulness. 


6 Estimate  the  probable  sharing  potential  and  needed  availability  at 
inceptiotv  mid  base  dGCuinentation  requirements  upon  this  potential.  If  the 
prospects  for  sharing  change,  then  alter  the  documeiitatiGn  and  availability 
requirements  appropriately  after  careful  consideration. 


A word  of  caution:  seemingly  one-shot  or  temporaiy 
programs  have  a way  of  evolving  into  frequently  used 
programs.  Increased  sharing  potential  can  result  in  lower- 
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cost  future  developinents,  provided  that  recognition  of  the 
potential  is  made  early  enough  for  proper  dbcumentalion 
and  announcement  provisions  to  be  made.  Even  subpro- 
grams within  a tempbraiy  or  one^rshot  program  can  often 
have  sharing  potential  if  properly  identifiedt  However,  it  is 
probably  not  Gost-effective  to  consider  sharing  low-cost 
programs  or  subprograms,  except  in  special  cases. 

7.  See  to  it  that  the  project  doGumentation  requirements  and 
documentation  plan  are  understood  by  personnel  responsible  for  document 
preparation,  distribution^  review,  approvals  and  updating. 


8,  Plan  for  the  announcement,  publication,  and  distribution  of 
documentation  to  intended  or  potential  users; 

9,  Institute  incentives  for  dbcumenitation  commensurate  with  the  priority 
given  to  dbcumentation  in  the  project 

10,  See  to  it  that  doGuments  and  status  reports  are  kept  current  and 
visible  to  all  pertinent  team  members  through  the  SDL. 

11,  Use  personal  contact  and  meetings  to  coordinate  policies^  decisions, 
and  interfaces  between  adjacent  parts  of  a system*  Confirm  and  record 
agreemertts  after-^the-fact  in  written  form.  Ensure  that  work  based  on  such 
agreements  proceeds  from  the  written  documentation,  not  on  recollections 
of  participants. 

12,  Insist  that  documentation  be  contributed  at  regular  intervals  into  a 
project  master  file  in  the  SDL,  in  addition  to  those  files  retained  at  the 
working  level.  Verity  that  there  are  adequate  provisions  for  updating  both 
types  of  files  and  for  querying  these  files  for  status  report  generation,  (If 
such  files  can  be  computer  based^  so  much  the  better,) 

13*  If  dbcumentation  is  nbt  up  to  standards  and  continually  seems  to  be 
troublesome,  j/op  all  activities  not  related  to  dbcumentation  and  bring  it  up 
to  standard. 

14.  Insist  on  simplieity,  directness,  clarity,  and  quality  of  expression  in 
dbcumentation  In  as  brief  a form  as  the  assigned  level  of  detail  permits. 
Only  when  this  can  be  achieved  can  ‘^more  doeumcntatibn''  be  made  to 
mean  "'better  dbcumentation.” 


1&3*2  Rules  for  Documentors 

The  following  siinple  rules  define  the  responsibilities  of  documentors; 
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1.  Understjind  thoroughly  the  project  doeunientation  requirements  and 
the  documentation  plan. 

2.  Understand  the  intended  use  of  the  document  and  the  needs  of  the 
intended  users. 

It  may  help  to  make  a list  of  all  personnel  groups  who 
fonn  the  audience  for  this  document,  and  to  imagine 
yourself  in  the  role  of  each  of  the  readers.  Clarify  what 
each  such  reader  would  want  in  the  sort  of  documehts 
being  prepared  before  writing  the  document.  If  necessary, 
interview  representatives  of  the  reader  groups. 

3.  Understand  the  overall  content  and  appropriate  level  of  detail  required 
for  the  dbciunent. 

4.  Verify  that  applicable  standards  have  been  selected  for  document 
format  and  content 

5;  Supply  documentation  that  satisfies  project  requirements,  fits  the 
documentation  plan;  communicates  with  the  intended  users  to  the  extent 
prescribed  by  the  level  of  detail,  and  adheres  to  specified  standards. 


6.  Submit  documentation  for  review,  correction^  and  amendment  in 
phases  conciirrent  with  other  software  development  activities. 


16.4  SUMMARY 

Adequate  doGumentation  of  computer  programs  is  clearly  an  essential 
element  of  efficient  and  economioaLl  use  of  computer  systems.  Good 
documentation  prevents  waste  and  unnecessary  costs  in  many  ways— by 
making  program  modifications  feasible,  by  making  redesigns  easier,  by 
making  internal  controls  work  better,  by  facilitating  the  work  of  auditors^ 
and  by  a host  of  other  ways,  all  equivalent  to  making  programs  usable  by 
others. 

Lack  of  needed  documentation  and  low-quality  documentation  are 
problems  in  human  engineerings  which  in  large  part  can  be  remedied  by 
setting  good  standards,  and  then  seeing  to  it  that  work  necessaiy  for 
doGumentation  is  performed  according  to  these  standards. 

T have  outlined  standard  levels  of  documentation  by  content  and  format, 
and  I have  given  typical  criteria  for  choosing  among  these  documentation 
levels.  Detailed  rules  for  flowcharts,  narratives,  information  flow^  decision 
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tables,  etc.,  are  contained  in  each  of  the  preceding  chapters  pertinent  to 
each  development  activity. 


1 


■ ■ ■ ■ 


A STANDARD  SOFTWARi 
PRODUCTION  SYSTEM 


As  computer  applic^ions  continue  to  advance,  there  is  an  increasingly 
more  intense  need  for  better  and  better  tools  to  aid  in  the  constructibn  of 
programs.  The  more  difficult  a task  is,  the  more  powerful  the  tools  must  be 
in  order  to  combat  the  burden  of  epmplex%  that  bears  down  on 
impleinontors. 


or,  perhaps,  inherently,  humaiis  do  better  than  computers,  such  as  creative 


m 

this  work  have  set  forth  standard,  structured  disciplines  that  attempt  to 
organise  such  processes,  and  thereby  enhance  individual  and  team 
productivity. 

There  are,  on  the  other  handj  matiy  software  development  tasks  of  a 
more  predefined  computational^  routine,  or  clerical  nature  that  computers 
can  do  quickly,  easily,  and  perfectly^,  but  which  humans  tend  to  do  in  a 
much  slower,  more  awkward^  more  difficult,  and  error-prone  manner* 
Suitable  automated  tools  to  reduce  this  routine  or  clerical  burden  during 
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software  generation  cun  significantly  reduce  programmer  time  and  effort, 
can  yield  more  reliable  programs,  and  can  produce  enhanced  documenta- 
tion* In  addition,  the  wide  use  of  automated  development  support  tends  to 
standardiy*c  programming  methods,  programming  stnietures,  program 
documentation,  and  all  other  areas  for  which  support  is  provided. 

The  purpose  of  providing  automated  support  is  to  make  it  as  easy  os 
possible  for  the  humans  engaged  in  a software  development  to  perform 
those  functions  which  only  they  can  provide,  and  yet  deliver  all  that  is 
expected  in  the  way  of  quality  programming,  proper  documentation, 
adequate  management  visibility,  and  good  configuration  control 

This  chajpter  discusses,  therefore,  the  standards  for  a well-fonned, 
efficient,  and  effective  program  production  support  system^  in  which  both 
human  and  automated  tools  play  a well-balancedi  integrated  part* 


17.1  AN  INTEGRATED  SOFTWARE  PRODUCTION 
SYSTEM 


Science,  technolo®',  indiistr)\  and  commerce  are  based  on  the  ability  to 
measure  things  or  phenomena,  to  describe  the  results  in  numerical  terms,  to 
make  comparisons,  to  make  decisions  based  on  these  conEparisons^  arid  to 
implement  these  decisions  using  standard  means.  In  order  that  the  software 
industry'  be  a stable  member  of  the  industrial  family,  its  products,  too,  must 
be  dfcscrlbable,  measurable^  and  implemeritable  in  standardized  ways* 
Predictability  of  function,  performance,  cost,  size,  and  other  qualities,  then^ 
becomes  a Gharacteristic  of  the  industry.  This  is  what  teGhndlogy  is  all 
about,  and  the  establishment  of  sound  production  toolis  into  a standard 
Ky*stem  does  much  to  bring  the  development  of  software  products  into  such 
a technological  arena* 

The  hounds  of  a programming  system  are  not  limited  merely  to  the  set  of 
automated  capabilities  one  may  find  in  a computer  library.  Rather,  a welb 
engineered  production  support  facility  must  consist  of  a number  of  other 
elements  taking  various  forms. 

17.1.1  The  Elements  of  a Standard  Productldh  System 

The  first  element  required  in  a good  production  system  (l^igure  17-1)  is  a 
body  of  sound,  effective  methodology  for  systematic  development  of  the 
software  items.  Such  methodology  is  produced  as  a result  of  dedicated 
study  into  the  problems  of  software  over  an  extended  period  of  time.  This 
methodology  is  continually  evolving,  in  cyclesv  as  new  discoveries  are  made 
and  as  amendments  and  modification*s  to  existing  teehnolo^  are 


S<?^r^,  17,1]  Intagrattid  Software  Production  System  173 

introduced.  DirccHons  lor  change  epine  about  through  observing  the  eflfeets 
of  changes  in  previous  cycles,  through  evaluation  in  pathfinder  projects, 
and  througl)  continuing  applied  research^ 


The  second  component  of  an  eflfective  programming  system  is  a set  of 
standard  practices,  human  production  disciplines,  and  software  user 
inuntials,  together  with  a us;ir  training  program,  which  identify  and 
fonnally  establish  the  adopted  teehnoto^  and  transfer  it  into  a regular 
implementatianal  and  operational  environment.  This  set  of  elements  also 


r- 
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Figure  17>1.  The  elQment&  of  a Standard  Production  Systein 
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serves  as  a concrete  point  of  reference  against  which  firm  evaluations  of  the 
established  technology  by  the  user  commimity  can  be  made  toward  possible 
future  modifications. 

The  third  component  of  an  effective  software  production  system  is  a 
central  service  facility*  or  programming  secretariat.  This  faciiiiy  supports 
the  production  of  software  in  a number  of  various  ways*  such^  as  by  serving 
as  a distributive  agency  for  standard  practice  instructions,  manuals,  and 
other  production  materials;  by  providing  data-^preparatioii  or  data-entr>' 
services;  by  updating  and  editing  textual  material  e.g.,  program  code, 
documentation,  and  other  material  as  contained  in,  and  eohtroHed  by,  the 
central  facility;  by  generating  or  updating  standard  graphic  material  held  in 
project  files  using  standard  automated  graphics  capahtfities;  by  perhaps 
administering  the  softXvare  change-control  process;  etc. 

The  first  three  parts  of  the  programming  system,  then,  are  oiiented 
toward  identifying  and  solving  the  human  factors  that  surround  software 
deveiopmentSi  These  have  largely  been  the  subject  of  this  monograph  up  to 
this  point  and  do  not  need  to  be  further  expanded  upon  here  in  any  great 
detail  The  fourth  and  remaining  part  of  the  system  consists  of  a set  of 
automated  aids  oriented  toward  reducing  the  time  humans  spend  (or  should 
he  spending)  producing  adequate  documentation,  status  reports,  and  the 
program  itself.  These  aids  are,  in  fact,  the  main  subject  of  the  remainder  of 
this  chapter. 


This  fourth  and  final  part  of  the  programming  system,  thus^  consists  of  a 
libra^  of  standard  langiiagcs  and  processors,  aiitqinatiG  production  aids, 
and  management-support  software,  plus  the  necessary  user  documentation 
and  training  in  the  application  of  such  tools  to  the  task  at  hand^  A full 
cempieinent  of  software  items  in  this  category  is  difiicuU  to  imagine; 
however,  jis  a starting  pointy  the  items  in  addition  to  a normal  complement 
of  coding  languages  should  include  facilities  to  aid  in  the  design^  testing, 
validation^  and  doGumeniution  (both  narrative  and  graphic)  of  programs 
and  data,  and  for  gathering  and  reporting  of  inanagement  information^  such 
us  costs,  schedules,  current  status,  prodiietivity,  etc.  Further,  provisions  for 
program  and  data  base  configuration  management  and  change  controli.  us 
well  as  features  that  permit  quality  assurance  metering  of  the  project 
dciivcrableSv  should  be  included 

The  support  facility  includes  a referetiGe  document  library  in  addition  to 
the  computer  program  library  above.  The  computer  libraiy  contains  a set 
of  utility  programs  and  subroutines  that  are  ayail^le  for  use  by  projects 
developing  software.  The  reference  document  library,  then,  contains  the 
needed  dOGumentation  for  users  to  be  able  to  apply  these  utilities  and 
subroutines  to  their  projects.  In  addition,  the  reference  document  libraiy 


I. 


Sec,  17 J\  integrated  Software  Produvtion  System  17S 

contains  standard  practice  instniGtions,  development  Jisctplines,  program- 
ming textbooks,  and  other  source  materials  needed  by  the  community  of 
program  development  and  implementation  personnel.  Since  creation  and 
maintenance  of  such  a library  is  a support  ftmetion^  its  administration  falls 
within  the  purview  of  the  programming  secretariat 

17.142  Glassification  of  Inriplementatian  Aids 

Automatic  implementation  tools  fall  into  three  categories^  which  1 shall 
refer  to  as  primary,  secondary,  and  tertiary  ^Figure  17-2).  Primaiy  tools  are 
those  facilities  absolutely  needed  to  build  a program  in  a practical  sense. 
These  facilities  ihclude  the  compilers  (or  asseniblers)  for  the  languages 
being  used,  program  (linkage  edit)  loaders,  data  and  text  editors,  and; 
usually,  an  operating  system.  Without  these  elements,  the  programming 
task  is  untenable. 

Secondary  development  support  aids  are  those  tools  which  can  be  used  to 
increase  software  productivity  and/or  program  reliabili^  significantly,  but 
which  are  not  needed  in  the  absolute  pragmatic  sense,  as  are  primary  tools. 
These  are  tools  that  are  justifiable  and  feasible  economically  whenever  their 
implcmentational,  operational,  and  sustaining  costs  are  more  than 
counterbalanced  by  the  savings  they  produce.  Since  the  allocation  of 


Primary  Aids:  Required  for  Programming 
Languages,  Gompilers 
Editors 
Loaders 

Operating  System 


Secondary  Aids:  tnerease  Pfoductiyity,  Reliability 
Graphics  Generation 
Document  Generation 
Program  Analyzers 
Execution  Monitors 
Debug  Facilities 
Management  Tools 


Tertiary  Aids:  Intangible  Benefits 
Prototypes  Under  Evaluation 


Figure  17^2.  CategbHes  of  implementation  aids 
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development  resources  to  the  generation  of  new  support  took  can  impact 
ongoing  project  delivery  schedules  as  well  os  their  dollar  costSi  the 
production  of  new  tools  may  not  always  be  advisable  when  these  are  iii 
series  with  critieahpath  tasks,  even  though  the  eventual  availability  of  such 
tools  could  show  a later  positive  economic  benefit  Such  tools  should 
always  be  carefully  justified  in  terms  of  projected  lifecycle  cost  savings 
through  increased  productivity,  in  terms  of  schedule  impacts  with  ongoing 
projects,  and  in  terms  of  software  quality  requirements  relative  to 
reliability,  manageability,  level  of  documentation,  etc. 

Tertiaiy  aids  are  automated  tools  of  less  significant  supporting  value  than 
secondary-class  tools,  Tertiaiy  aids  are  those  with  intangible  economic  or 
program  reliability  benefit  within  a given  production  systeiUv  These  tools 
could  Gonceivabiy  be  justified  on  some  basis  other  than  economics^ 
schedule,  or  program  quality;  however,  that  basis  should  be  closely 
scrutinized  before  the  tool  is  allowed  to  become  a forma!  part  of  a 
‘‘standard  production  tystem/'  Tertiaiy  tools  may,  however,  appear  from 
time  to  time  in  a standard  production  system  on  an  evaluational  or  trial 
basis,  either  to  be  upgraded  to  secondary  (or  even  primaiy)  status  if  the 
evaluation  is  favorable,  or  to  be  dropped  if  the  evaluation  is  unfavorable^ 

In  specitying  a set  of  support  tools  for  software  development,  the  needs, 
desires,  and  frustrations  of  personnel  must  be  consider^  in  addition  to 
economiG  and  schedule  factors.  Moreover,  the  tools  should  exhibit  huiiian 
engineering  qualities  so  as  to  be  effective,  generally  applicable,  and  eas>'  to 
use  over  a wide  spectrum  of  applications  within  the  standard  system. 

When  a set  of  tools  is  implemented^  each  must  be  absolutely  correct, 
validated  to  the  point  that  it  can  be  used  with  i00%  confidence.  How  eke 
can  one  use  such  a tool  to  validate  other  software  products  or  to  enforce 
standards^  unless  the  tools  themselves  are  faultless? 

A final  criterion  1 would  impose  is  the  near-absolute  machine 
independence  of  the  programming  system  application-user  interface  across 
the  entire  spectmm  of  host  systems  bdng  used^  within  a minimal  set  of 
Gonventioi^  imposed  by  the  host  hardware  and  software  environinent.  Such 
conventions  as  log-on  proGedures,  interactive  vs.  batch  pperation,  file 
naming  conventionsi  tape-mounting  protocols,  complement  of  peripherals, 
and  word-length  restrictions  are  veiy  likely  to  vary  from  host  to  host; 
nevertheless^  automated  tools  should  be  able  to  respond  to  these  diflFerent 
environmental  constraints  and  yet  maintain  effectiveness^  ThuSi  while 
materials  produced  in  one  standard  production  system  may  not  be 
absolutely  portable  in  source  form  to  another  such  production  system^  there 
should^  nevertheless,  be  a large  base  of  commonality  and  uniformity  in  the 
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products  each,  with  absolute  portability  of  applications  programs  lacing 
the  goal. 

When  user  interfaces  cannot  be  made  to  support  absolute  portability, 
they  nuist,  as  a mitiiiiium  requirement,  support  program  mobility,  Tliat 
degree  of  portability  vs.  mobility  sought  is  one  that  should  balance  any 
incre;tscd  running  costs  of  user  programs  against  the  decreiLsed  production, 
Gonversioii,  documentation*  and  other  constituent  costs  during  the  total 
software  life  cycle. 


17.1.3  The  Programming  Data  Base 

Autoinated  or  not,  the  production  of  a piece  of  software  utilizes  a data 
base,  consisting  of  design  information,  coding  information,  testing 
infonnattGii,  management  information,  and  documentation.  Without 
automatioiK  a groat  deal  of  time  is  spent  locating,  transforining,  and 
extracting  information  from  this  data  base  to  create  meaningful  views  of 
the  items  extractecL 


If  automated,  the  complete  data  base  could  well  reside  in  an  integrated 
set  of  files,  accessed  and  manipulated  by  standard  processors^  The  computer 
system  then  bceoines  the  design  medium,  the  docimientatioiirGompositiDn 
medium,  and  the  software  management  medium,  in  addition  to  being  the 
more  usual  coding,  debugging,  testing,  and  operational  media. 

Each  element  of  a programming  data  base  is  generally  interdependent  on 
the  others,  whether  autoinated  or  not.  But  if  automated  (Figiire  17-3),  for 
example,  procedural  design  inforiuation  can  coiieeptually  generate 
flowcharts  or  data-flow  diagrams,  if  needed,  and  can  be  automatically 
output  with  the  corresponding  narrative;  code  can  be  audited  automatically 
for  conformance  with  standards  and  with  the  procedural  design;  project 
status  information  can  be  coileeted,  such  as  numbers  of  modules  completed 
or  stubbe<l  in  devSign,  code,  or  test  activities,  frequency  and  t\pe  of  errors 
coimnittcd^  etc.;  test  design  criteFia  for  traversing  each  program  flowline 
can  be  identified;  editing  and  updating  of  design,  code,  testing,  and 
documentation  can  be  controilled;  all  accesses  to  the  programming  data 
base  can  deposit  activity  information  back  into  the  management  data  base 
for  project  status  reports  generation;  and  eorifigiiration  management 
standards  can  be  enforced. 

The  programming  data  base  is,  therefore,  one  of  the  key  elements  in  the 
overall  concept  of  the  standard  software  production  system.  Combined  with 
its  level  of  access,  it  forms  the  basis  for  recording  and  .storing  of 
programming  data,  provides  the  vehicle  for  the  otganizatipn  and  Gontrol  of 
a programming  project,  serves  as  the  means  of  commiiniGation  behveen 
developers,  and  interfaces  program  development  personnel  to  each  other 
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Figure  17*3.  Tite  programming  data  base  In  a production  syi^m  contains  ail  Information 
from  which  dpcumentetlon.  reporting,  and  execution  emanate 


and  to  the  computer.  The  principal  management  function  of  the  data  base 
is,  then,  to  maintain  a current  and  exact  Gonfijgitratipn  of  a program  under 
dievelopinertt  for  all  viewers^  Further  dismission  of  management  data 
processing  appears  in  Section  17.7* 

17.1w4  The  Programming  Secretariat 

The  programming  secretariat  is  an  individual  or  group  of  personnel  who 
support  all  development  projects  within  a certain  purview,  much  like  a 
secretarial  pool  aids  office  management  by  performing  a body  of  common, 
centralized  derical  functions  for  a number  of  separate,  but  similar,  users 
(iFigure  17-4)i  Some  of  the  fiinGtions  ^ically  performed  by  a secretariat 
Were  mentioned  earlier:  data  preparation  and  data  entry  services, 
distribution  of  manuals  and  production  materials,  document  preparation 
and  revision,  management  reporting,  archiving,  etc.  In  addition  to  these 
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fuudttotis^  the  SGcrctariat  probably  miisl:  ako  have  the  means  to  generate 
new  elements  and  n^aintain  existing  eapabilities  of  the  software  production 
system;  to  Gdiitrol  the  coniigiiration  and  integrity  of  that  system^  and  to 
collect  user  feedback  relative  to  the  funGtioning  and  use  of  that  system. 

Each  software  development  project*  as  dkeiissed  in  Chapter  10^  contains 
a central  focal  point  (its  Software  Development  Lihrar>")  for  all  project- 
generated  materials.  The  programming  data  base  being  accumulated  by  an 
pngping  project  is  owned;  administered;  controlled,  and  maintained  by  the 
SDL  for  tliat  project  However,  the  automated  tools  that  are  used  by  all 
projects  to  create,  update,  and  extract  information  from  the  data  base  will 
not  be  considered  here  to  be  a part  of  any  particular  project  SDL,  but, 
rather,  to  be  a part  of  the  centralized  programming  support  library  within 
the  standard  sofbvare  production  system. 

In  actual  developmental  operations^  a project  may  interface  with  its  SDL 
totally  through  the  secretariat,  as  In  Chief  Programmer  Team  [24|] 
operations,  or  the  team  may  interface  with  its  SDL  directly.  Regardless  of 
the  interfaeing  inode,  the  contents  of  a project  SDL  are  entirely  determined 
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by  personnel  within  that  development  project,  not  by  the  secretariat  The 
format  of  a project  SDL  data  base,  however,  is  dictated  by  the  standards  of 
the  production  system,  not  the  development  team  (Figure  17-5).  The 
secretariat  is  responsible  for  maintaining  control,  integrity,  and  security  of 
all  software  items  placed  within  its  purview. 

Except  for  normal  “housekeeping”  operations,  all  clerical  support  tasks 
carried  out  by  the  secretariat  are  performed  only  on  the  direct  request  of 
project  personnel^  and  then  only  when  such  support  can  be  provided  by  the 
secretariat  without  project  assistance  or  direct  supervision.  Directions  from 
the  project  may,  for  example,  come  by  way  of  original  graphics  or  coding 
sheets  for  ciitiy,  by  way  of  marked-up  listings  for  update,  or  through  any 
medium  for  which  a standard  secretariat  support  procedure  exists. 


Rguie  17-5.  Visual  and  actual  views  of  the  SOMcontents  olthe  SCl  are  determined  by 
the  project^  but  the  format  of  the  data  base  is  set  by  standards  of  the  production 
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In  operations  where  secretariat  support  is  absent  or  limited*  the  standard 
support  procedures  and  processors  should  he  available  for  use  directly  by 
development  team  persoiineL  However,  the  advantage  in  cost  aiid  acGuracy 
of  having  human  clerical  tasks  performed  by  Glerically  trained  individuals 
instead  of  programmers  is  obvious. 

To  support  software  developments,  the  secretariat  needs  a eonglomerate 
set  of  skills  that  cut  across  clerical  and  tecltnical  boundaries.  Personnel 
engaged  in  clericai  support  of  programming  require  a set  of  qiialifiGations 
such  as  typing,  filing,  and  other  business  praptices  normal  to  an  office 
environment;  however,  since  the  computer  system  forms  the  medium  for 
these  activities,  support  mdividiials  must  also  be  skilled  in  the  use  of 
keypunch  or  keyboard  terminal  equipment  and  must  understand  the 
procedures  for  preparing  data  and  performing  each  intended  task  oh  the 
computer. 

If  the  secretariat  is  also  charged  with  the  creation  and  sustaining  tasks 
associated  with  the  automated  support  fiinctions,  then  it  must  contain 
personnel  of  the  type  and  caliber  found  in  the  regular  devdbpment  projects 
and  in  the  sustaining  engineering  and  maintenance  groups.  If  training  of 
project  personnel  in  the  use  of  accepted  organizational  software 
development  disciplines*  organizational  standards,  human/machine  inter- 
faces, project /secretariat  interfaces,  etc.,  are  also  required^  then  personnel 
with  skills  appropriate  to  perform  such  training  are  needed;  If  enforcement 
of  standard$  or  software  Gonfigtiration  integrity,  control  and  management 
are  named  as  required  development  support  functions*  then  appropriate 
personnel  to  administer  such  functions  may  also  appear  in  the  secretariat. 


17^1^5  Hdst  System  and  Environment  Considerations 

At  this  point,  let  me  define  what  is  probably  a minimum  set  of 
requirements  for  a host  system  to  acGommodate  the  computer  library  and 
operations  within  the  production  system  to  be  discussed.  These  require- 
ments are  not  meant  to  specify  a recommendied  set  of  equipment;  the 
project  size,  equipment  on  hand*  and  intended  tasks  also  affect  the 
maximally  effective  set  rather  drastically.  Instead,  the  configuration  given 
here  is  meant  to  display  my  assumptions  relative  to  the  production  ^stem 
needs. 


The  host  /stem  envisioned  is  depicted  sehematically  in  Figure  17-^.  The 
complement  of  equipment  as  seen  by  each  user  includes  an  interactive 
keyboard  terminal  and  card  reader  for  data  and  program  entiy,  magnetic 
tapes  and  online  direct  access  media  for  data  storage,  and  a high-speed 
printer,  character  display  terminal^  and  plotter  for  outputs. 


162  SUmdard  Sa^Hcare  Pmduetion  System 


[CHAP.  17 


Since  much  of  every  software  development  task  is  the  development  of 
easily  readable  documentation,  I will  suppose  that  I/O  and  stomg^  media 
support  both  upper  case  and  lowercase  alphabetfc  characters.  A CPU  size 
of  SOK  bytes  over  and  above  operating  system  and  compiler  pverheads  has 
been  estimated  necessaiy  by  Tinanoff  and  Luppino  [25];  however,  much  can 
still  be  accomplished  within  host  ^^ems  having  smaller  CPU& 

I will  suppose  that  the  host  operating  ^tem,  which  controls  the 
execution  of  the  production  system  tasks  (Figure  17-7),  also  controls  the 
allocation  of  storage  on  the  mass  storage  device.  If  more  dian  one  user  is 
reqiiitml  to  operate  the  production  system  at  one  time  in  concurrency,  then 
the  operating  ^Stem  will  also  administer  and  accommodate  the  allocation 
of  resouiices  among  these  users. 

I coiic^Bde  that  existing  ^temsdevel  software  will  probably  need  to  be 
revised;  rewiiften,  or  refined  before  it  can  be  inte^ted  into  a uniform 
interface  across  the  standard  production  ^tem.  Such  utilities  as  hie  f/O 
hsmdlets,  program  loaders,  linkage  editors,  compiiers,  assemblers,  tmct 
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Rgure  17-7.  The  standard  producUbn  system  Interface  configuration  (the  operating 
system  administers  execution  of  programs,  allocates  and  manages  storage  and  other 

fesoureas) 


editors,  and  other  typical  vendor-supplied  software  items  can  often  be 
modified  (especially  on  mihi^  and  rnicroi^omputer  hosts)  to  foriii  the  base 
for  the  standard  software  production  system  and  thereby  ease  the 
development  task  that  implements  the  standard  system^  at  least  on  an 
interim  basis.  Substandard  software  should  be  replaced  as  soon  as  it  is 
feasible  to  do  so. 

The  use  of  a higher-level  language  • (concurrent  Pascal!)  has  been 
demonstrated  to  be  effective  in  writing  operating  system  software  f26]  by 
Bniich-Hansen^  who  estimated  a 20-30  man-year  effort  was  acGomplished 
by  him  in  only  a few  months.  From  the  production  poiiit  of  view,  he 
concludes,  it  is  both  realistic  and  attractive  to  replace  huge^  ineffective 
“general  purpose^  operating  systems  with  a range  of  small,  efficient  systems 
for  special  purposes. 
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17*1.6  User  Considerations 

One  must  recognize  that  the  efficiency  of  a team  praducing  software  is 
influenced  to  a signiflcant  degree  by  the  intended  efficiency  of  the  software 
to  be  produced  and  by  the  production  tools  available  to  do  the  job.  For 
example^  if  a program  must  (unquestionably)  be  written  in  assembly 
language  for  a provably  necessary  enhanced  execution  speed,  the 
produetivify  of  the  programmer  is  likely  to  be  lower  than  if  programming 
could  take  place  using  a higher^level  language  having  a less  speed-efficient 
compiler,  unless  the  production  system  can  supply  services  to  equalize  this 
imbalance.  Brinvu-Hansen  [26]  has  estimated  that  only  about  4%  of  an 
operating  system  needs  to  be  in  assembly  code. 

Another  capabiUty  that  influences  development  productivity  is  its 
operational  mode.  An  interactive  operational  environment  permits  its  users 
on  immediate  view  of  the  response  of  a program^  but  the  computer  costs 
for  these  are  usually  somewhat  greater  than  those  for  the  same  views 
supplied  in  a queued  batch  environment.  One  generally  finds  that  there  is 
an  overall  developmental  cost  savings  when  there  is  ah  interactive 
capability  due  to  the  decrease  in  user  time  required  to  interact  with  the 
system.  Some  inefficiency  in  computer  operations  can  thus  usually  be 
tolerated  (at  least  in  non^realrtime  programs)  whenever  the  rise  in 
computer  costs  due  to  this  inefficiency  is  dominated  by  pei^onnel  cost 
savings,  brought  about  by  improved  usability. 

Software  development  spans  a time  when  a great  deal  of  user  interaction 
with  the  evolving  program  is  required,  regardless  of  whether  the 
environment  is  interactive  or  not.  Provisions  to  facilitate  interactive 
interplay  during  this  time  are  probably  very  advisable  in  terms  of 
development  cost  savings,  even  if  these  raise  running  costs.  However,  if  the 
operational  usage  of  the  program  must  thereafter  continually  pay  for 
inefficiencies  that  facilitated  program  development,  the  cost  savings  may  be 
eventually  reversedi 


To  couhteraGt  such  a possibility,  one  might  propose  a production  system 
that  would  balance  or  equalize  program  life  cycle  costs  by  making  the 
development  task,  perhaps,  somewhat  harder  for  the  sake  of  decreased  later 
operational  costs^  Alternatively,  and  more  usefully^  the  tystetn  can  GOhtain 
modes  and  processors  which  promote  both  rapid  development  and  efficient 
operations;  this  chapter  supports  the  latter  alternative^ 

The  $tandard  software  production  system  of  this  chapter  will  thus 
support  both  inteipretive  simulation  and  compiled  modes  of  operation. 
Programs  can  be  developed  interactively  using  the  interpreter,  or  processor 
executing  an  intermediate  code,  for  checkout  and  testing;  Once  Gorrect> 
these  programs  may  bo  cotppll^  and  optimized  for  acceptance  testings 
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delivery,  and  subsequent  operations.  The  Implications  of  this  position  on 
the  development  of  programming  languages  for  the  system  have  been 
explored  and  endorsed  by  Wegbreit  f27]. 

17,2  THE  STANDARD  PRODUCTION  SYSTEM  SUPPORT 
LIBRARY 

As  1 indicated  earlier,  the  support  libraiy  contains  not  only  the  computer 
programs  that  aid  software  production,  but,  also,  the  manuals  and  practices 
that  enable  users  to  employ  these  aids.  The  aids  themselves  represent 
various  mixes  of  functions  that  together  provide  the  following  categories  of 
support: 

• Word  processing 

• Graphics  generation 

• Management  status  monitoring  and  reporting 

• Programming  of  routine  or  clerical  tasks 

• Program  generation 

• Program  loading,  linking,  and  execution 

• Program  analysis  and  performance  monitoring 

• Program  repair 

• Source  data  management 

• Data  protection  and  integrity 

To  varying  extents,  each  of  the  aids  will  be  characterized  by  such 
operational  qualities  as: 

• Cost-effective  operation 

• Reliability 

• Generality  and  power 

• Application  independence 

• Simplicity  of  use 

• Conciseness  and  terseness  in  user  interplay 

• Naturalness  of  interplay  dialogue 

• Consisteney  with  other  aids 

• System-independent  operation 


1B6  Standard  Software  Production  System 


[CHAP.  17 


Gosi  eflfeetiveness,  of  coursCj  relate  to  the  cost  of  performing  a task 
using  an  aid,  as  opposed  io  perfoming  the  task  without  it;  reliability  refere 
to  the  average  degree  to  which  the  aid  performs  efieetively  in  program 
production,  as  compared  to  its  advertized  full  capability.  Generality, 
power,  and  application  independence  all  refer  to  the  scope  of  tasks 
accomplished  by  the  aid:  to  the  number  of  different  tasks  performed,  to  the 
amount  of  work  accomplished  by  each  task^  and  to  the  range  of  proj^ts 
that  may  find  the  aid  useful. 


Simplicity  in  use  characterizes  features  that  eliminate  unnecessary 
variations  in  notations;  such  features  enhancing  simplicity  make  an  aid 
easier  to  use  because  they  reduce  the  number  of  forms  and  concepts  that 
must  be  learned,  Conciseness  and  terseness  of  expression  enhance  usability 
by  reducing  the  user/inachine  mterface  dialogue.  Naturalness  is  a measure 
of  the  degree  to  which  the  symbology  of  user/machine  communication  is 
humanly  understandable  and  easily  remembered  over  long  periods  of  time, 


Consistency  with  other  aids  refers  to  an  overall  conformance  with  usage 
standards,  coordinated  with  respect  to  redundancies  among  the  various  aids. 
Consistency  would,  for  example,  require  that  whenever  two  aids  perform 
the  same  functions  (overlap  in  capabilities),  then  the  input  forms  and 
protocols  would  be  the  same  for  each.  Identical  forms  would  be  required, 
whether  input  emanates  from  a terminal,  file,  or  card  reader;  output  forms, 
ditto. 


More  specifically,  suppose  that  aids  A mid  B both  can  operate  on  files  of 
data,  and  each  can  duplicate,  and  thereby  create  new  files;  consistency 
would  not,  then,  permit  using  differing  syntaxes,  such  as: 

COPY  ftlel  TO  filc2 
DUPLICATE  fiJe2  FROM  filcl 

but  would  require  conformance  to  a common  syntax,  say,  the  first.  No  third 
aid,  say,  C,  coiild  use  this  syntax  to  rename  ftlel  as  but,  instead,  would 
have  some  different  syntax,  as: 

msfE  file!  TO  filc2 


wi7h  a natural  “semantic  proximity.”  Finally,  no  fourth  aid,  D,  could  then 
use  the  MOVE  syntax  to  deposit  values  into  variable  storage,  but,  instead, 
would  have  to  employ  a syntax  with  a wider  implicit  “semantic 
differential,'*  such  as: 
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Li^variabh  = expression 

System-independent  operation  refers  to  constancy  in  operation  as  viewed 
by  the  user,  ^ has  been  discussed  earlier  (Section  17.1.5). 

I will  not  atteinpt  in  these  pages  to  provide  a complete  or  detailed  set  of 
requirements  or  functional  specifications  for  systematizing  and  automating 
a programming  data  base.  Bather,  I will  tty  to  identify  and  outline  the 
salient  GotiGepts,  key  features,  skeletal  format,  and  rationale  for  a typical 
programming  system  support  libraty.  A more  detailed  set  of  typical 
requirements  and  specifiGations  for  a “Program  Support  Libraiy”  for  use  by 
Chief  Programmer  Teams  [24]  has  been  defined  in  the  works  of  Luppino 
and  others  [25^28;]. 

Figure  17-8  depicts  the  skeletal  structure  of  the  programming  data  base 
and  the  processors  forming  the  basils  for  the  standard  production  support 
libraiy  to  be  discussed.  The  processors  to  be  discussed  are  those  for 
languages,  automatic  flowcharting,  text  processing,  and  management 
reporting.  Linkage  editors,  loaders,  job-control  supervisors,  etc.,  will  not  be 
covered.  As  a result,  the  design,  documentation,  program,  and  management 
data  base  entries  are  perhaps  more  fully  described  than  are  some  of  the 
other  files  and  documents  in  the  data  base. 


17.3  STANDARD  PROGRAMMING  LANGUAGES  AND 
LANGUAGE  STANDARDS 

Programming  languages  form  the  primary  tools  by  which  computer 
programs  are  constructed.  Without  a language  well-suited  to  the  task  at 
hand,  the  most  elegant  of  secondaiy  tools  will  prove  inadequate  for 
composing  high-quality  programs,  albeit  secondaiy  tools  may  permit  one  to 
build  the  poor  program  more  quickly  or  better  than  would  take  place 
without  such  aids. 

Those  features  of  a standard  language  that  implement  procedural 
hierarchic  refinement  and  control  logic  structures  constitute  what  I will 
refer  to  as  the  control  sublanguage  of  the  language.  Much  of  this  text  has 
already  been  devoted  to  discussion  of  topics  that  influence  the  design  of  a 
control  sublanguage;  Chapter  7 and  Appendix  G contain  standards  for  the 
control  sublanguage  (CRISP)  that  I shall  be  using  here  in  examples* 

Those  features  of  a standard  language  that  are  not  part  of  the  control 
sublanguage  and  that  are  not  concerned  with  I/O  constitute  what  I shall 
refer  to  as  the  base  sublanguage. 


188  Standard  S(^waire  Productim  System  [CHAP,  17 


Sec, 


189 


17,3]  Standard  Programming  Languages 

The  base  language  deals  pdndpally  with  data  declaratiion  and  storage 
management,  scalar  types,  features  for  data  structuring,  and  operations  on 
data.  The  Department  of  Defense  requirements  document  [S9j  for  higher- 
order  computer  languages  Gontains  an  excellent  discussion  of  features 
needdi  in  a modem  base  sublanguage. 

The  remainder  of  the  standard  language  is  the  1/0  sublanguage.  An 
excellent  summary  of  I/O  sublanguage  capabilities  for  a number  of  higher- 
order  language  appears  in  the  worfe  of  Goodenough  et  al  {30].  Further 
discussion  of  I/O  capabilities  appears  in  Section  17.3.4,  following, 

It  would  be  preferable^  in  the  interests  of  standardization  and  language 
commonality,  to  have  only  one  standard  language  in  the  libraiy  repertoire. 
There  is  ample  evidence  {31,32]  that  such  a requirement,  however,  is  not  a 
pragmatic  one  when  implementation  and  operational  costs  are  considered 
As  an  alternative,  then,  there  may  be  a set  of  standard  languageSi  each 
coordinated  with  the  others,  all  available  to  users,  and  all  rigorously 
policed  and  maintained. 

A coordinated  set  of  standard  languages  should  then  differ  only  in  the 
ranges  of  each  of  its  component  sublanguages,  appropriate  to  the  intended 
application  set  (non-real-time  languages,  for  example,  would  not  contain 
the  FORK-JOIN  structure);  the  ^stem  programming  language  may  permit 
certain  bit-level  manipulations;  etc.  Features  common  to  any  two 
programming  l^guages  must,  for  standardization,  have  the  same  syntax. 

It  is  imperative  that  each  implementation  not  contain  source4aj:iguage 
features  which  are  not  defined  in  the  language  specifiGation,  and,  moreover, 
any  implementation  of  a language  feature  not  explicitly  permitted  by  the 
language  must  be  expressly  forbidden.  This  is  necessary  to  guarantee^  that 
the  use  of  programs  and  software  subsystems  will  not  he  restricted  to  a 
particular  h'  >t  by  virtue  of  its  having  a unique  version  of  the  language. 

Such  a restriction  represents  a commitment  to  freeze  each  source 
language,  inhibit  innovations  and  growth,  and  confine  the  language  set  to 
the  current  state  of  the  art.  In  return,  standardization  buys  stability,  wider 
applicability  of  software  tools,  reusable  software,  greater  software  visibility, 
and  increased  payoff  for  tool-building  efforts.  Standardization  does  not, 
however,  necessarily  disallow  optimizations  which  are  host-system  unique, 
nor  does  it  prevent  growth  and  modification  as  authorized  by  a responsible 
change  control  board. 

It  is  equally  important  that  every  implementation  of  a particular 
language  implements  the  entire  language*  If  individual  processors 
implement  only  a subset  of  a language,  there  is  then  no  chance  for  software 
portability,  and  there  is  no  guarantee  that  users  may  access  standard 
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supported  Itbraries  or  appliGation  programs  iihplGmentcd  using  another 
version  of  the  same  language. 

B<equirihg  that  the  full  language  be  implemented  will  be  expeasive  only 
if  the  language  is  larger  complex,  and  nonruniform.  A number  of  smaller 
Gompatible  languages  that  can  each  communicate  with  the  other  and  with 
libranes  of  specialized  features,  support  packages,  and  complex  operations 
should  be  the  goal 

There  is  no  room  in  this  text  to  discuss  all  the  factors  to  be  taken  into 
account  in  language  design.  TI>e  interested  reader  is  referred  to  the 
interesting  works  of  Nicholls  [33]  and  others  [29,30,31,32]  for  such 
information,  A few  highlights  are^  however,  worth  mention  here. 

In  keeping  with  user  utility,  those  tasks  of  a routine  nature  associated 
with  language  processing  should  be  included  and  standard  for  all  languages 
in  the  standard  set  These  include  (l)  automatic  checking  6f  variables, 
functions,  and  parameters;  (2)  runtime  checking  of  data-range  integrity 
(e.g.,  subscripts  within  range);  (3^  automatic  formatting  and  annotation  of 
listings;  (4)  cross-referencing  and  indexing  of  variables,  procedure  names, 
literals,  and  other  useful  program  elements;  (5)  pathranalysis,  program 
tracing,  and  other  debugging  features  under  programmer  control;  (6) 
performance  monitoring  for  calibration  of  execufciGn  effleiency;  (?) 
generation  of  meaningful  diagnostic  messages  for  anomalous  behavior;  and 
(8)  linkage  generation  to  independent  compilation  units,  with  consistency 
checks  on  passed  parameters. 

17.3*1  Structuring  Features 

Without  discussing  the  detailed  syntax  and  problem-oriented  perform* 
ance  features  of  a programming  language,  let  me  address  some  of  the 
structural  and  methodology-oriented  aspects  of  the  compiler  which 
implements  that  language.  (l  am  excluding  the  assembly  language  processor 
as  a “eompiler”  here.)  T envision  that  compiler  as  forming  a concrete 
medium  for  the  program  procedural  and  data  design  (embodying  a program 
design  language,  such  as  CRISP-PDL),  and  run  the  gamut  from  there  all  the 
way  down,  in  hierarchically  refined  stages,  to  the  executable  code. 

At  the  highest  level,  the  compiler  acts  as  a CRTSP-PDL  processor, 
accumulating  program  design  algorithms,  cataloging  procedures,  cross- 
referencing  names,  and  matching  (and  linking)  such  things  as  procedural 
name  usages  with  procedure  definitions.  Those  procedures,  functions, 
operators,  data  names,  etc.,  which  appear  referenced,  but  which  have  not 
yet  been  given  formal  descriptions  in  the  design  and  are  not  recognizable  as 
elements  of  the  programming  language,  are  used  to  inform  the 
programmers  that  such  items  need  refinement  Eventually,  when  the  design 
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is  complete  wbea  all  refinements  have  reached  the  programming 
language  levd,  then  no  unresolved  references  appear,  and  the  output  code 
is  the  completed  program. 


The  source  descriptions  in  the  early  design  can  be  viewed  as  “non- 
compilable,”  as  no  compiler  output  need  appear  unless  desired.  However, 
the  compiler  is  continually  prompting  the  programmerv  “What  do  you 
mean  by. , naming  a textual  string  used  by  the  programmer,  but  as  yet 
unrecognized  by  the  compiler.  At  each  stage,  the  compiler  compiles  what  it 
can,  links  what  procedures  and  data  names  it  can,  and  informs  the  user  of 
items  it  cannot  handle  as  yet;  in  addition,  it  flags  i^tactic  errors  for 
removal. 

Such  a compiler  can  even  create  dummy  stubs  automatically  (or 
interactively),  given  an  outline  of  what  stubs  in  general  should  do  (for 
example,  do  nothing,  print  the  name  invoking  the  stub  and  return,  prompt 
the  user  for  input,  etc.).  That  is,  the  compiler  is  capable  of  producing  an 
executable  program  in  some  form  or  other  whenever  directed,  at  any  point 
in  the  program  developments 

The  first  code  produced  by  the  compiler  is  probably  interpretive,  and  is, 
perhaps,  incrementally  compiled,  procedure  by  procedure.  The  production 
mode  is  interactive,  and  the  program  status  can  be  probed  at  any  point 
where  the  execution  pauses  for  programmer  query.  Values  for  variables  can 
be  viewed  or  altered  during  such  pauses,  and  the  program  can  then  be 
continued  until  a later  pause.  Because  it  works  iii  this  incremental, 
interpretive,  interactive  mode,  the  compiler  needs  to  have  the  capability  to 
display  and  alter  values  by  symbolic  name,  as  well  as  to  edit  and  to  re- 
execute  parts  of  the  program.  The  final  program,  produced  by  the 
compiler,  is  an  optimiz^  executable  code,  suited  to  the  operational  mode 
desired  (interactive  or  batch  or  both). 


As  for  languages:  Even  with  the  capability  for  hierarchic,  semantic 
refinement  built  into  a compiler,  it  is  a fundamental  error  to  believe  that 
program  developers  should  be  confined  to  thinking  in  a procedurally 
oriented  language.  There  will  always  be  a need  for  a * -cogitation  medium” 
separate  from  a computer.  The  ma^jor  responsibility  in  language  design  rests 
upon  the  creation  of  a tool  which  facilitates  stating  the  solution  to  a class 
of  problems  once  the  solver  has  reached  that  point  in  the  solution  process 
where  computerized  aid  can  feasibly  be  standardized.  The  compiler  I have 
described  above  attempts  to  aid  the  solution  process  by  bridging  the  gap 
between  certain  program  abstractions  and  their  concrete  representations  in 
code. 
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17*3^2  An  Example  of  Mierarchfc  Compiling:  Ordered  Search 

Before  going  into  more  detail  Goncerning  features^  syntax,  and  semantics 
of  a language  suitable  for  the  standard  production  system,  let  me  illustrate, 
by  means  of  a hypothetical  compiler,  how  the  procedural  design  abstraction 
hierarchy  might  be  acGommodated; 

Problemi  A set  of  integers  is  contained  in  the  1-dimensional  array,  TABLE  of 
size  N;  the  integers  are  orderedi  so  that  TABLE[i]  < table! i + i],  brackets 
denoting  subscripts.  Design  and  implement  a procedure,  SEARCH  (VAL. 
FOUND) , to  seek  the  integer  variable  val  among  the  table  items,  and  set  a 
Boolean  variable  FOUND,  to  true  or  false  accordingly. 

Solution:  The  solution  method*  is  to  partition  portions  of  the  array 
iteratively  for  search  into  a left  part  and  right  part  by  some  as-yet 
unspecified  criterion.  Ths  first  part  orthis  solution  is,  then,  the  CRISP-PDL 
procedure: 


procedure:  SEARCH (VAL:  Integer  , FOUND: boolean) 

Select  initial  portion  to  tje  searched 
1 pop  while  (more  than  one  element  in  portion) 
reduce  portion  to  be  searched 
repeat 

examine  chosen  part  and  set  FOUND 
end procedure 


At  this  point,  the  compiler  has  recognized  only  the  underlined  keywords, 
the  procedure  name  and  variables  to  be  passed,  and  the  procedure  and  logp 
structures.  The  compiler  then  asks  for  definitions  of  the  strings^  “Select 
initial  portion  to  be  searched,*'  "more  than  one  element  in  portion/* 
“reduce  portion  to  be  searched/’  and  “examine  chosen  part  and  set  FOUND/* 


The  programmer  responds,  in  this  hypothetical  language,  with  a set  of 
refinements: 


to  select  initial  portion  to  be  searched 

declare  L.  R:  integer  local  to  SEARCH 

L:«1.  R:=N 

endto. 


*Per  Brinch-Hanscii,  Stnictured  Programming  Class  Notes,  JPL  Employee  Development 
Glass,  SprfJig,  1975. 
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to  reduce  portion  to  be  searched 

partition  current  portion  into  left  and  right  parts 
K (solution  iRipossible  in  left  part) 
select  right  part 
(else) 

select  left  part 
endif 
end  to 

The  progammer  has  chosen  not  to  respond  at  this  time  to  the  other 
elements  asked  for  above«  The  compiler  then  asks  for  definition  of  elements 
"partition  current  portion  into  left  and  right  parts/*  "solution 
impossible  in  left  part/*  "select  left  part/*  and  "select  right  part/* 
The  next  set  of  refinements  entered  are: 

to  partition  currene  portion  Into  left  and  right  parts 
set  C to  rightmost  index  of  left  part 
endto 


macro:  solution  impossible  in  left  part  means 
TABLE  tej  < VAL 
endmacro 

to  select  left  part 
R;  =C 
en.dto 

. ^ select  right  part 
L:«C+1 
endto 

macro:  more  than  one  element  in  portion  means 
L<R 

endmacro 

to  examine  chosen  part  and  set  FOUND 
JT  (VAL=TABLE(L} ) 

FOUND; «TRUE 
(else) 

FOUND: -FALSE 
endif 
endto 

At  this  point,  the  compiler  has  recognized  all  elements  of  the  solution 
except  "set  c to  rightmost  index  of  left  part/*  and  it  finds  no 
declaratlcris  for  ARRAY  and  C,  whereupon  is  entered: 
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dec 1 are  C:  integer  1 oca } to  SEARCH, 

TABLE;  array  [l.;  N]  of  integer  global^ 

Mi  integer  global 

Whether  the  search  is  a linear  sequencing  through  table,  or  a binaiy 
segmentation  of  the  search  portion  into  two  nearly  equal  parts  on  each 
cycle,  or  almost  any  other  kind  of  ordered  search,  it  is  centralized  and 
controlled  by  the  single  procedure  "set  C to  rightmost  index  of  left 
part,”  although  it  is  possible  that  some  searches  (e.g>,  a I^ibonacci 
partitioning  [34])  might  also  require  some  additions  to  “select  initial 
portion  to  be  searched/* 

Carrying  the  example  here  further,  I shall  suppose  a binary  search  is  in 
order,  in  which  case  the  following  refinement  is  entered  so  as  to  divide  the 
search  region  by  2 iii  each  cycle: 

to  set  C to  rightmost  index  of  left  part 

C;a  IP( (LrH) /2)  <*truncates  to  integer  Part*> 
end  to 

The  concrete  declarations  and  operations  above,  such  as  ''declare.*/' 
and  “Ci«  IP(  (L-fRiyZ)/*  are  assumed  to  be  in  that  regular  part  of  the 
language  syntax  not  needing  further  refinement.  I have  taken  liberty  in 
assuming  that  the  reader  comprehends  what  is  meant  by  these  constructions 
in  this  hypothetical  language  without  explicit  definition  (which,  of  course, 
the  hypothetical  user's  manual  would  provide). 

The  program  development  is  now  complete,  as  all  elements  have  been 
recognized  by  the  compiler.  On  seeing  how  procedures  are  defined,  the 
compiler  then  provides  a suitable  linking  method.  In  the  example  shown, 
all  procedv  tes  are  probably  inserted  in-line  in  the  object  code. 


17.3*3  Data  Structuring  Features 

Each  programming  language  in  the  system  must,  of  necessity,  be  able  to 
declare  data  structures  and  to  operate  on  those  structures  as  appropriate  to 
solve  the  problem  at  hand,  and  each  of  these  languages,  thereforei  needs  a 
common,  standard  syntax  with  which  to  declare  its  data.  A programming 
language  tends  automatically  to  set  standards  for  data  structure 
declarations,  and  the  standard  syntax  should,  therefore,  be  designed  so  as  to 
permit  hierarchic  development  of  data  structure  specifications  as  discussed 
earlier  in  Chapters  4 and  12. 

In  Chapter  2,  I defined  a data  stnicture  as  a representation  of  the 
ordering  and  accessibility  relationships  among  data  items^  without  regard  to 
storage  structures,  or  implementation  considerations.  In  this  sense,  data 
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structures  lie  midway  In  the  mapping  process  that  transforms  the  problem- 
solution  domain  into  the  storage  and  computation  domain.  Data  structures 
are  characterized  by  a set  of  attributes  accorded  to  the  data  items  to  be 
manipulated^  Among  these  attributes  are; 

• Ranges  of  values  for  data  items 

• Helationships  among  data  items 

• Means  of  declaration  and  creation 

• Rights  and  means  of  access 

• Valid  sets  of  operations  when  accessed 

The  specification  of  a set  of  attributes  defines  a data  type.  The  simplest 
data  types  for  data  items  in  a language  are  called  fundamental  scalar  types. 
In  FORTRAN,  for  example,  integers  and  reals  are  the  primary  fundamental 
scalar  types  permitted.  Extended  scalar  types  refer  to  wider  classes  of 
scalars  defined  in  or  through  the  language  syntax^  but  without  direct 
accessibility  to  the  underlying  scalars  that  form  the  extended  types.  For 
example,  a FORTRAN  complex  number  is  formed  from  two  reals  (simple 
scalars),  and  all  references  to  these  components  are  explicit^  being  achieved 
only  through  the  defined  set  of  operations  and  functions  for  complex 
numbers. 

Data  that  contain  scalar  types  as  elements  or  sub-eleirtents  are  called 
structured  types.  The  simplest  structural  ^es  in  a language  are  said  to  be 
fundamental  or  *‘built-in''  structural  types.  FORTRAN  permits  only  fixed- 
dimensional scalar  arrays  as  its  fundamental  structure*  PASCAL  contains,  in 
addition,  record  and  file  structures. 

Declaration  is  the  notification  to  the  compiler  of  data  type  attributes; 
when  storage  is  actually  allocated  at  runtime  or  reserved  statically  at 
compile-time  for  later  operations,  the  structure  is  said  to  have  been  created 
or  bound.  The  access  domain  of  a structure  is  composed  of  that  set  of 
operations  permitted  to  read,  write^  or  otherwise  manipulate  it. 

For  reliability,  most  modern  languages  now  provide  some  measures  of 
protection  and  privacy  so  as  to  catch  the  simpler  forms  of  inadvertent 
violation  of  access  domains.  Such  languages  are  said  to  be  typed,  as 
opposed  to  languages  that  permit  arbitrary  operations  on  a variable.  For 
example,  FORTRAN,  which  permits  character  strings  to  be  stored  in 
integer-declared  arrays  and  operated  on  either  as  integers  or  characters,  is 
untyped  in  this  respect  PASOAL,  on  the  other  hand,  is  fully  typed,  not 
even  allowing  integers  to  be  added  to  reals  without  explicit  type 
conversion. 
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Access  attributes  are  declared  forms  of  access  rights,  such  as  literal  or 
constant  (read  only)  and  variable  (read/write),  qualified  by  such  modifiers 
as  ghbal  (accessible  by  the  entire  program  or  a set  of  programs),  local 
to. . .(accessible  only  within  a given  list  of  modules  and  their  submodules), 
readable  . .(read-access  only  by  listed  modules  and  their  submodules), 
and  writable  by. , .(write -access  only  by  listed  modules  and  their 
submodules). 

Data  stnictures  are  also  eharacterizahle  by  storage  creation  attributes, 
such  as  static  allocation  (fixed  at  compile-time),  controlled  (determined 
dynamically  at  runtime),  automatic  (dynamic  nmtime  alloeation  of 
temporaiy  data  stnictures  and  release  after  use),  and  variants  of  these,  such 
as  based  storage  (controlled  storage  in  which  temporaiy  copies  are  created, 
stacked,  manipulated,  and  destroyed  in  block-structured  programs). 

Data  stnicture  declarations  may  also  establish  initicd  values  to  be  present 
upon  creation. 

An  abstract  data  type  is  that  which  can  be  described  by  a cascading 
hierarchy  of  data-type  definitions  whose  primitives  are  fundamental  types  in 
the  programming  language.  The  design  procedures  outlined  in  Chapters  4 
and  12,  in  fact,  describe  data  structure  design  as  the  process  of  abstract 
data  type  definition. 

Programming  languages  that  provide  abstract  data  type  declaration 
facilities  to  vaiying  degrees  have  been  in  existence  since  about  1967  when 
SIMULA-67  appeared.  Since  then,  there  have  been  an  ever-increasing 
number  of  such  languages,  e.g.,  ALGOL-68,  PASCAL,  concurrent 
PASCAL,  and  PASQUAL.  A useful  bibliography  of  papers  concerning  data 
types  and  programming  languages  may  be  found  in  the  work  of  Tennent 
[35].  Specifications  for  a Data  Description  Language  (DDL)  have  also  been 
published  [31]  by  the  CODASYL  group.  The  Department  of  Defense 
requirements  for  Its  higher-order  language  [39]  state  that  it  be  typed,  allow 
for  the  definition  of  new  data  types  and  operations  within  programs,  and 
permit  ranges  of  values  that  can  he  associated  with  a variable,  array,  or 
record  component  to  be  any  built-in  type,  any  defined  type,  or  a contiguous 
subsequence  of  any  enumeration  type* 

Specification  techniques  for  data  abstractions  have  been  treated  by 
Liskov  and  Zilles  [36],  who  concluded  that  there  is  no  single  specifiGation 
technique  that  is  universally  better  than  others  in  terms  of  providing 
mathema^jV-a!  inambiguity,  ease  of  construction,  ease  of  comprehension, 
and  mininr,iiity  of  expression  in  describing  the  pertinent  usage  attributes  of 
the  structure,  without  having  to  divulge  purely  constructional  details 
extraneous  to  the  problem. 
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Hoare  [3Tl,  m fact,  concluded  that  it  is  totally  unrealistic  to  suppose  that 
any  high-level  language  or  automatic  process  (or  even  a generalized, 
integrated  data-base  management  system)  could  be  made  to  produce 
satisfactory  implementations  from  abstract  definitions,  in  the  general  case. 
Rather,  it  always  will  be  necessary  for  the  programmer  to  synthesize  some 
of  his  abstractions  using  fundamental  operations  and  declarations, 
programmed  levels  of  access,  coding  conventions  and  standards,  and 
documented  data  relationships. 

The  syntax  of  the  base  language  must,  therefore,  accommodate  each  of 
the  attributes  necessary  for  humans  to  build  concrete  data  structures  from 
virtual  abstract  data  types.  The  basic  attributes  needed  include  an  adequate 
set  of  fundaniental  scalar  and  structure  types  from  which  other  types  can  be 
generated.  Such  a set  might  well  include  the  scalar  types 

• Integer;  bounded  integer 

• Real;  bounded  real 

• Character;  string  of  characters 

• Boolean;  logical 

• Complex 

• Member  of  enumerated  set 

• Double  precision  (integer,  real,  complex) 

and  the  fundamental  structures  over  each  scalar  type  may  well  include 

• Array  (indexed  access,  single  scalar  type  elements) 

• Record  (field-name  access,  arbitrary  scalar  type  elements) 

• Buffer,  or  sequence  (sequential  access,  single  scalar  type  elements) 

• Set  (membership  access,  discrete  scalar  type  elements) 

• List  (chained  access  via  pointers  to  single  scalar  type  or  record 
elements) 

• String  of  boolean 

In  addition,  the  following  first'-ordcr  compound-structural  types  contribute 
enormously  toward  the  ease  by  which  data  abstractions  can  be  encoded: 

• Array  of  records 

• File  of  records 

• List  of  records 

In  each  of  the  compound  structured  types  above,  the  records  have  scalar 
elements  only. 
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The  capability  to  compound  structural  types  arbitrarily  to  the  cases  in 
which  elements  identified  above  as  scalars  can  ihsteaid  he  any  previously 
specified  data  type  is  precisely  what  is  needed  for  abstract  data 
definitions*  The  extent  to  which  such  features  can  be  made  feasible  within  a 
programming  language  syntax  determines  how  much  of  the  abstraction 
must  be  programmed  using  other  means^ 

In  order  that  storage  binding  time  be  programmable,  the  base  language 
must  not  only  permit  static  allocations  of  data  structures,  but,  also^ 
dynamic  allocations  and  reallocations  during  execution.  Automatic  and 
based  storage  can  generally  be  simulated  by  special  attention  to  controlled 
storage  procedures.  The  capability  to  declare  an  initial  value  to  be  supplied 
when  the  structure  is  created  may  be  included  as  a basedanguage 
requirement 

In  order  that  storage  locations  be  bound  in  a conveniently  programmable 
way,  data  ownership  declaration  options  are  needed.  Structures  occupying  a 
global  area  should  link  to  access  hinctions  by  the  same  means  used  to 
declare  those  structures;  for  example,  a named  variable  declared  to  be 
global  should  be  accessible  by  its  name  throughout  the  program,  regardless 
of  the  order  in  which  variables  are  declared  in  its  separately  compiled 
parts.  This,  of  course,  is  contrary  to  the  FORTRAN  practice  of  locating 
elements  in  COMMON  by  position,  rather  than  by  name.  The  base- 
language  processor  may  require  a special  linking  loader  to  accommodate 
separately  compiled  modules. 

Linking  of  stmetures  declared  to  be  scoped  within  a module  and 
accessible  by  any  of  its  descendant  (perhaps  separately  compiled) 
submodules  may  also  require  special  features  within  the  compiler  and 
loader  not  only  to  communicate  structure  names  but,  perhaps,  the  module 
hierarchy  as  welL  The  limited  use  of  data  structures  by  a set  of  operations 
is  a subcase  of  a more  geher?!  problem  that  in  which  access  rights  to 
resources  are  controlled  and  administered  by  the  language  processor. 
Certain  structures  (literals)  are  meant  to  be  read-only  by  any  module;  'others 
(variable)  are  meant  to  be  arbitrarily  read  or  written  into  by  any  authorized 
module;  still  others  conceivably  may  be  read-only  to  some  modules  and 
write-only  (or  read/write)  to  others. 

A language  that  checks  and  administers  such  rights  of  access  to  resources 
must  implicitly  or  explicitly  permit  programmers  to  communicate  these 
rights  to  the  structures  being  accessed.  Most  commonly,  localization  of 
access  only  is  available,  achieved  through  separate  compilation  or  through 
block  structure  in  the  language;  functions  and  subroutines,  which  are 
externally  refereneeable  but  compiled  together  using  mutual  data  among 
themselves,  then  form  a level  of  access  to  their  local  data  structures. 
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The  standard  languages  should,  however,  support  the  definition  of  levels 
of  access  to  resources  within  each  compilation,  and  not  necessitate  the, 
perhaps,  unnatural  dislocation  of  code  segments  into  separate  compile 
modules.  Moreover,  localization  of  functional  access  within  levels  should 
be  possible;  access  functions  that  form  a sublevel  of  access  vi^ithin  a given 
level  of  access  should  not  be  referenceable  above  that  level  of  access. 

17.3.4  Input/Output  Capabilities 

The  processes  of  input  and  output  are  in  truth  merely  mappings  from 
data  stmctures  in  one  medium  to  data  structures  in  another.  Among  data 
structures  in  core^  such  mappings  are  frequently  referred  to  as  type 
conversions;  however,  in  I/O,  the  mappings  are  generally  called /ormatting. 
An  I/O  type  consists  of  a set  of  objects  or  values  associated  with  physical 
devices  characterized  by  special  selection  and  assignment  operators,  special 
organizations  and  associated  sets  of  operations,  and  an  end-of-l/O  property. 
Most  higher-order  languages  support  a variety  of  different  I/O  devices, 
transmission  modes,  access  rules,  organizational  protocols,  and  structural 
attributes. 

I/O  data  types  are  not  always  explicit  in  a language^  but  a language  that 
supports  I/O  functions  must  include,  in  the  narrowest  sense,  the  following 
operations  and  exception  conditions; 

• Open  medium  for  accessj  assign  buffers  (can  be  implicit) 

• Close  medium  access,  deallocate  buffers  (may  not  be  necessary) 

• fieorf,  or  select  an  object  from  the  medium  (buffer) 

• Write^  or  assign  an  object  into  a medium  (buffer) 

• End-of-medium,  no  more  data  accessible  froiii  medium 

• No-such-device,  medium  cannot  be  identified 

• Access-error,  improper  access  operation 

• Physical-error,  medium  physical  failure 

An  open  I/O  medium  has  at  least  a certain  minimum  set  of  assigned 
attributes,  among  which  are 

• Medium  type 

• Label  or  name  (if  a file) 

• Access  restrictions  (read-only,  write-only,  etc.) 

^ Buffer  designation 

Additional  attributes  define  the  I/O  data  structure  for  proper  conversion 
into  or  from  physical  storage  (character  vs,  binary,  record  vs.  stream  access, 
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stream  in  character  mode  vs.  line  mode,  records  blocked  vs.  unblocked, 
formatted  vs.  free-form,  etc 

The  interfaces  (Figure  17^9)  between  the  base  sublanguage  and  the  I/O 
sublanguage  are  the  I/O  buflter,  format  speciftcation,  and  attribute  table. 
The  buffer  must  be  capable  of  receiving  or  being  assigned  any  valid  data 
type  addressible  in  the  base  language  (actually,  just  scalar  data  ^es  and 
combinations  of  them  that  can  be  packed  into  aggregates  with  word  or 
character  alignment).  Both  formal  and  default  formats  must  he  aecommo- 
dated,  and  format  generation  must  be  under  programmer  control. 

The  programability  of  the  I/O  sublanguage  is  a matter  of  assigning  or 
accessing  buffer  values,  setting  attribute  table  entries,  specifying  format 
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parameters,  and  reacting  to  exception  conditions.  The  ability  to  support 
I/O  functions  to  special  devices  is  partially  dependent,  however,  on  the 
presence  of  data  l^es  that  map  directly  to  the  values  implicit  in  the 
devices^  In  the  interests  of  mihimizing  host  system  dependencies  and 
promoting  language  commonality  among  installations,  it  is  important  that 
the  allowable  set  of  I/O  functions  be  limited  to  a subset  of  capabilities 
supportable  on  all  standard  hosts. 

For  this  reason,  the  internal  attributes  of  the  I/O  media  should  not  be 
accessible  by  the  applications  programmer.  Formats  and  other  programma- 
ble attributes  should  probably  be  recordable  directly  on  output  media,  right 
along  with  the  output  data,  so  that  automatic  type  checking  can  be 
accommodated  (to  some  limited  degree)  when  that  data  is  read  back  in  by  a 
program.  Devices  (such  as  keyboard  terminals)  that  are  input-only  must 
then  handle  only  a single  type  (e.g.,  character),  but  with  conversions  to 
scalar  types  and  aggregation  into  structures  via  a specifled  input  format. 
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The  quality  of  a computer  program  can  often  be  significantly  related  to 
the  design  medium  in  which  that  program  is  developed,  embiyonically  and 
evolutionarily,  from  the  ideas  that  permeate  the  programmer's  mind,  to  the 
completed  programming  specification.  Such  a medium  must  foster  the 
expression  of  such  ideas  easily  and  quickly  (sometimes  before  they  fade 
from  memory),  and  must  permit  flexible  and  facile  alterations,  additions, 
and  deletions  to  these  ideas  as  the  design  evolves.  Moreover,  the  expression 
of  the  design  should  be  as  graphic  as  a "‘picture  of  the  program'"— yet  not 
be  the  program,  nor  constrained  by  the  rigorous  syntax  of  a compilable 
computer  language.  At  the  final  evolutionaiy  stage,  such  descriptions 
should  form  the  principal  program  design  document. 

. A “Program  Design  Language,-'  or  PDL,*  is  a formalized  embodiment  of 
such  a design  aid,  and  can  take  many  forms.  Probably  the  most  familiar 
form  of  a PDL  is  flowcharting.  Flowcharts  have  many  advantages  and  many 
disadvantages,  which  will  not  be  named  or  argued  here,  except  to  say  that, 
while  being  veiy  graphic,  they  are  nevertheless  very  limited  in  what  they 
can  do  for  the  program  designer  because  of  the  limited  space  available  for 
expression,  because  they  are  primarily  procedure-Griented,  because  of  their 
inflexibility  toward  alteration  or  revision,  and  because  of  the  expense 
required  to  draft  them  in  a “finished"’  form. 

*This  aLTon)'m  also  stands  for  “Procedure  Definttibn  Language/'  “Procedure  Design 

Language/*  and  other  equivalcni^. 
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The  compiler  described  earlier  iii  Section  17*3.1  had  the  PDL  capability 
; built  in,  interactively  building  up  the  program  through  stepwise- 

refinement-dialog  with  the  user.  However,  there  is  more  to  a programming 
I task  than  can  be  expressed  in  a procedure-oriented  language*  There  must 

; also  be  a way  to  explain  to  readers  of  the  documentation  the  significance  of 

j certain  operations,  the  goals  to  be  met  by  programmed  functions  before 

■ they  are  programmed^  the  assumptions  that  have  been  made  at  a particular 

J point  in  the  design,  the  reasons  why  the  given  constructions  were  used  (or 

I why  others  were  ruled  out),  and  illustFaticns  which  facilitate  the 

I understanding  process* 

i 

Such  program  rationale  can,  of  course,  be  kept  apart  from  the  program 
or  merged  into  it  somewhat  in  the  form  of  comments;  both  methods  have 
many  admirable  qualities:  Comments  tend  to  explain  local  effects  in 
procedures  at  their  points  of  occurrence.  Separate  narrative  and  graphics 
are  usually  better  for  analyses  and  more  global  explanations  of  program 
i function. 

In  the  remainder  of  this  section,  permit  me  to  focus  on  some  text- 
formatting and  design-reporting  features  of  a simple  hypothetical  CRISP- 
PDL  processor  consistent  with  later  flowcharting  requirements  (Section 
17,5),  A more  detailed  description  of  CRISP-PDL  may  be  found  in 
Appendix  G, 

Each  CRXSP-^PDL  input  line  consists  of  possibly  three  fields:  a prefix,  a 
cosmetic,  and  the  program  text  The  prefix  contains  possibly  a step  number 
within  the  module  (usually  chosen  to  correspond  to  a box  on  a flowchart) 

• and,  perhaps,  a subroutine  or  function  cross-reference*  The  cosmetic 

portion  consists  of  spaces  and  vestigial  fiowlines^  so  as  to  present  an 
indented  listing,  which  displays  many  of  the  features  of  a flowchart  as 
illustrated  earlier  in  Chapter  7* 

The  text  field  of  the  input  is  of  two  varieties:  a controHogic  text  and 
non-control-logic  text.  Control-logic  text  fields  begin  with  a control 
keyword,  such  as  if,  loop,  repeat,  or  a left  parenthesis  Such  keywords 
signal  the  processor  to  increase  or  decrease  the  indenting  level  and  to  add, 
I delete,  or  modify  the  vestigial  flowUnes*  The  headings  of  nest^  structures 

if*  else,  etc,)  increase  the  indenting  level  and  add  flpw;lines; 
ending  of  nested  structures  (e.g*,  endif,  endcases,  repeat,  etc*)  decrease 
the  indenting  level  and  eradicate  flowlines.  Abnormal  and  paranormal  exits 
5 (exit,  return,  stop,  and  system)  cause  no  change  in  indenting  level,  but  do 

i show  a flowline  exit  of  the  current  nesting  level  back  to  the  appropriate 

i level 
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The  output  of  the  CRISP-PDL  processor  consists  of  a table  of  contents 
or  module  directoiy,  a tier  chart,  and  the  cosmetized  CRISP-PDL  with 
cross-references  of  identifiers^  subroutines,  and  functions.  Figure  17-10 
summarizes  the  CRISP-^PDL  inputs,  processing  functions,  and  outputs^ 
Inputs  are  the  source  file  being  processed  and  control  data  that  selects 
output  options.  Processing  consists  of  cosmetizing  source  Hnes^  as  described 
earlier,  the  accumulation  of  module  and  identifier  names,  page  numbers, 
and  cross-reference  material,  and  the  output  of  such  material  as  directed  by 
control  data. 


A more  detailed  data-flow  diagram  is  shown  in  Figure  17-11  for  purposes 
of  describing  the  functions  more  clearly.  Neither  the  names  of  symbols  nor 
the  physical  structure  of  the  program  internal  data  flows  necessarily 
corresponds  to  those  in  the  program  internal  design.  Symbols  are  numbered 
to  identify  input  (l),  processing  (2),  or  output  (3),  just  as  in  Figure  17-10;  an 
additional  D^ey-dccimal  identifier  serves  to  individualize  the  boxes  into 
separate  functions. 


Text  appearing  between  a module  ender  and  the  next  module  header  is 
copied  directly  to  the  listing  without  cosmetization  or  diagnostic  checking. 
Each  line  is  scanned,  however,  since  it  potentially  contains  identifiers.  It  is 
just  as  important  to  locate  identifiers  in  commentary  as  it  is  to  locate  them 
in  the  procedural  listing. 

Each  module  begins  a new  page,  as  does  any  narrative  that  follows  a 
module  end  and  a new  module  header.  (Each  module  end  signals  a page 
advance.)  The  output  report  starts  the  CRISP-PDL  listing  at  page  1 (the 
table  of  contents  and  front  matter  are  given  Roman  numeral  page 
numbers). 

The  output  report,  in  its  fullest  form,  consists  of  the  following  sections  or 
parts,  in  order; 

• Title  page 

• Table  of  contents 

• Program  directory 


Processing 

Output 

• Cosmetize 

• Accumulate 
Linkages 

• Print  Report 

• Directary 

• Tier  Ghaft,  Stubs 

• Ustingr  Cross‘fefs  : 
^ Piagnostics^.^^^^ 

Rgure  17*10.  The  GRISP-PDL  HlPO  diagram 


,.,A 


L 
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• Tier  chart 

• SWb  status  report 

• Cosmetized  source  listings  first  module 

• Intermodule  text 

• Cosmetized  source  listings  second  module 

• 

• Glossary  and  cross-rrferences 

• Statistics  of  program 

The  full  set  of  CRISP-PDL  forms  appears  in  Appendix  G. 


17.5  FLOWCHARTING  FROM  CRISP-PDL 

The  equivalence  between  CRISP-PDL  and  flowchart  structures  is  not 
coincidental  The  exact  one-for-one  correspondence  was,  by  design, 
intended  to  facilitate  software  production  ly  making  design-level  graphics 
available  and  suitable  for  program  documentation.  Programmers  who  claim 
they  do  not  need  flowcharts  to  design  and  implement  programs  can  use 
CRISP-PDL  as  a much  more  writable,  flexible,  and  (to  them)  readable 
specification  of  the  program  procedure.  Processing  the  GRISP-PDL 
produces  the  more  graphic  documentation  for  others  to  read^  automatically 
and  at  low  cost 

Still  others  will,  perhaps,  choose  to  work  with  flowcharts  on  a primary 
basis,  but  using  the  entry  and  update  capabilities  of  a text  editor,  rather 
than  manually  drawing  and  redrawing  their  own  charts. 

In  this  section  1 describe  a simple  flowcharter  for  the  CRISP  language, 
called  CRTSPFLOW,  It  is  simpler  than  most  general-purpose  flowcharters, 
such  as  AUTOFLOW  [38],  BELLFLOW  [39],  etc.,  because  it  only  draws 
structured  flowcharts,  one  module  to  a page,  and  permits  no  off-page 
connectors;  it  conforms  such  charts  to  the  layout  standards  used  throughout 
the  two  volumes  of  this  work. 

The  flowchart  ^mibols  plotted  by  CRISPFLOW  will  have  varying 
dimensions  according  to  the  text  to  be  contained  in  each.  Nevertheless, 
standard  ANSI  [40]  aspect  ratios  (widthiheight)  are  maintained.  The  letters 
and  “F”  always  label  binaiy  decision  symbols,  true  always  on  the  left. 
Structures  always  have  straight-down  flow  paths;  that  is,  branch-collecting 
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nodes  are  located  exactly  below  the  branching  vertex,  etc,  GASB^lause 
identifiers  become  labels  on  the  various  paths  emanating  from  the  multir 
decision  brancK  Figures  17-12  and  17-13  show  an  example  of  CRISP- 
FLOW  input  and  output. 

Horizontally  striped  symbols  result  upon  encountering  DO  or  GALL 
statements  in  the  CRISP-PDL  source;  vertically  striped  symbols  are  drawn 
in  response  to  the  k^word  CALLX.  The  remainder  of  the  text  on  a line 
enters  the  box,  the  procedure  name  above  and  the  comment  field  below. 

Loop-collecting  nodes  are  distinguished  as  open  circles;  decision- 
Gollecting  nodes  by  filledrin  circles. 

CRTSPFLOW  does  not  chart  off-page  connections  nor  any  other 
unstructured  fornix  No  matter  how  targe  a CRISP-PDL  module  is»  it  is 
sized  to  fit  on  a standard  21-1/2  X 28  cm  (8-1/2  X 11  in.)  page  by  scaling 


PROCEDURE:  SAMPLE 


<*18  SEPT  75* > 


MOD#  1,3.5 


,1 

.3 

.4 

.5 

.6 


J/Sl 

.8 

.9/XS2 


• 11 

.12 


<*Thi:s  sample  module  demonstrdtes  the  GRISPFLOW 
<*syntax  with  a hypothetical  message  transmission 
<*system.  Statements  denoted  STl  through  5T4  are 
<*unspeGif1od  here,  and  the  READ  routine  is 
<*external  to  the  set  of  documentation  for  which 
<*t ha  flowchart  Is  being  produced. 


IF  (UNALLOGATED) 
CASE  (MODE 


STl 


ST2 

S.T3 

->(3| 


ST4 

:..ENDCASES 

GALL  OPEN  (MODE)<*CHANNEL  IS  MODE  NUMBER.*> 
->(ELSE) 

LOOP  WHILE  (AVAILABLE) 

: CALLX  READ(CHR)<*READ  CHARACTER* > 

I CALL  WRiTE{e-HR)<*WRITE  CHARACTER*> 

I ..REPEAT 


:,.ENDIF 

DO  CLdSE<*MESSAGE  .SENT*> 

DO  RELEASE<*DISGGNNECT  GHANKEL*> 
ENDPROCEDURE 


Rgure  17-12.  Example  of  GRISPFLOW  source  format  for  a PROCEDURE  fipwchait 
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down  all  symbols  accordingly.  The  number  of  symbols  that  can  be 
flowcharted  is,  therefore,  set  by  readability,  not  the  caprice  of  CRISP- 
FLOW. 


The  charting  algorithm  is  very  simple  in  concept,  and  worth  mentioning 
here  as  an  interesting  design  example^  For  each  module  in  the  CHISP-PDL 
source,  the  top-level  control  structure  appears  as  the  following  three  steps: 

DO  PARSE  a tree  structure  for  the  inoduie*> 

DO  LAYOUT  <♦  locate  and  size  the  chart  on  a pago*> 

DO  DRAW  <«plot  symbols  and  flow! In es  on  the  page*> 

The  PARSE  step  scans  each  CRISP-PDL  statement  to  extract  the  step 
number,  cross-reference,  keyword,  and  comment  fields,  storing  this 
information  into  a node  of  a tree  structure,  representing  the  graph.  This 
node  is  attached  to  the  tree  by  arrangement  of  son/brother  pointers 
associated  with  the  nodes,  to  record  the  nesting  hierarchy  of  statements  in 
the  CRISP-PDL,  Figure  17-14  illustrates  the  tree  format  for  the  SAMPLE 
program. 

The  LAYOUT  step  applies  a 'super-box”  approach  to  size  and  arrange  the 
boxes  on  the  page.  The  layout  procedure  scans  the  parser-generated  tree  in 
a post-order  traverse  (see  Section  7.3.2  and  [34]),  and  for  each  node  forms  a 
transparent  "super-box,”  which  encloses  the  super-boxes  of  all  its  subtrees 
(nested  elements).  The  size  of  each  super-box  (stored  with  the  other  node 
information)  is  determined  by  the  type  of  node  (i.e„  statement)  to  which  it 
corresponds,  together  with  the  sizes  of  the  super-boxes  of  each  of  its 
subtrees.  The  post-order  walk  permits  the  structure  of  the  tree  to  be 
utilized  as  a "reduction  system”  or  means  to  layout  the  chart  in  a 
comprehensive,  bottom-up  first  pass  through  the  tree.  As  the  nodes  at  each 
level  in  the  tree  are  scanned  and  "reduced”  to  super-boxes,  they  are  used  in 
turn  to  construct  the  super-boxes  of  the  nodes  at  the  next  higher  level.  This 
procedure  continues  until  the  top-level  statements  of  a module  are 
combined  into  the  super-box  for  the  entire  module. 

The  DRAW  step,  now  having  the  size  of  the  total  chart,  scales  its  siiper-box 
to  fit  the  plot  page,  centers,  and  performs  a pre-order  scan  [34]  of  the  tree, 
during  which  it  establishes  coordinates,  draws  the  boxes,  fills  them  with 
text,  and  connects  them  with  flowlines,  arrows,  and  callecting  nodes,  all  in 
one  final  pass  through  the  tree. 

The  box-arrangement  algorithm  described  above  is  a compromise 
between  a “dynamic  programming”  approach  and  one  that  forestalls 
repetitive,  brute-force  search  schemes,  to  allow  rapid  chart  layout  with  only 
mode.st  memory  demands.  The  “super-box”  approach  yields  veiy  well 
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arranged  charts  without  packing  boxes  as  densely  (or  as  ‘'cleverly”)  as  might 
be  achievable  using  one  of  the  slower  generation  schemes. 


17.6  TEXT  AND  PROGRAM  FILE  EDITING 


A means  for  text  editing  is  one  of  the  primary  needs  in  eveiy  sbfUvare 
development.  Both  the  design  documentation  (procedure  and  narrative)  and 
the  source  code  (including  data)  for  the  compiler  are  in  the  form  of  text 
files  that  require  constant  application  of  the  editor  from  inception  to 
program  delivery,  and  on  into  sustaining  and  maintenance  throughout  the 
program  life  cycle. 

The  text  editor  is,  therefore,  a general-purpose  tool  for  program 
production  whose  syntax  and  semantics  must  be  engineered  to  fit  in 
uniformly  with  the  other  aids  in  the  programming  system.  It  is  the  means 
by  which  all  files  operating  within  the  standard  program  production  system 
are  created  and  updated. 

As  with  other  aids  mentioned  in  this  chapter,  a detailed  set  of 
requirements  for  a text  editor  is  beyond  the  present  scope.  However,  some 
of  the  highlights  are  worth  discussing. 

The  first  interesting  aspect  of  the  editor  I would  propose  is  a feature 
that,  while  administering  changes  to  program  elements  (doGumentation, 
CRISP-PDL,  code,  tabular  data,  etc.),  would  at  the  same  time  perform 
some  of  the  management  functions  needed  to  monitor  program  develop- 
ment Some  of  the  simple  things  that  can  be  done  are  to  (l)  redate  any 
module  altered  by  the  editor;  (2)  remove  configuration  control  codes  (in  the 
comment  field  of  a CRISP-PDL  module  header,  for  example)  until  the 
approval  cycle  (Section  10.4,2)  reestablishes  the  module  validity;  (3) 
identify  changes  to  either  code,  CRISP-’PDL,  or  documentation  which  were 
not  also  accompanied  by  changes  in  the  others  as  well;  (4)  automatically 
queue  or  Identify  all  altered  CRISP-PDL  modules  or  narrative  elements  for 
flowcharting  or  other  output;  (S)  automatically  register  program 
completion  status  reports  with  the  management  data  base  when  modules 
are  added  or  completed  (or  deleted);  and  (6)  register  statistics  on  editing 
transactions  with  the  management  data  base.  Such  functions  provide  the 
visibility  into  programmer  activities  needed  by  management  to  assess  the 
project  s healths  diagnose  trouble  spots,  and  monitor  the  team  progress. 

The  other  requirements  on  the  text  editor  relate  to  its  effectiveness  as  a 
productivity-increasing  production  tool  It  should,  of  course,  be  able  to 
operate  on  all  text  files  used  within  the  production  system.  For  efficiency 
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and  flexibility  it  should  accommodate  both  sequential  and  random-access 
files,  with  unrestricted  record  and  file  lengths. 

The  editor  needs  to  be  both  an  interactive  tool  and  a programmable  one 
as  well  That  is,  it  should  function  directly  in  concert  with  the  user  at  a 
terminal  in  interactive  dialogue,  and  it  should  operate  when  given  pre- 
stored or  hatch-entered  instructions. 

The  programming  language  should  be  simple,  easy  to  learn,  and  easy  to 
remember,  with  syntax  coordinated  among  the  other  languages  in  the 
standard  set,  as  discussed  earlier  in  this  chapter.  The  user  should  be  able  to 
define  (and  modify)  file  and  record  structures,  whether  defined  within 
program  elements,  or  whether  existing  in  some  predefined  “structure  file.** 

Files  may  require  both  public/private  and  read/write  security  keys;  the 
editor,  moreover,  should  enjoy  no  special  privilege  with  respect  to  private 
or  read-only  files.  The  user  in  each  case  is  expected  to  supply  proper  access 
codes  for  the  operations  and  files  to  be  accessed.  The  philosophy  for  file 
security  assumed  here  is  one  that  protects  users  from  non-maiicious, 
inadvertent  usages  by  others,  rather  than  malicious  breaches  of  security  for 
illegal  purposes.  Protection  of  the  latter  type  is  needed  in  many 
applications,  and  can  be  added  as  a requirement  in  such  cases  (at  some 
expense,  no  dGUbt), 

Some  of  the  features  needed  are: 

a.  Editor  can  be  initiated  from  another  processor  without  toss  of 
workspace  or  file  status  upon  return  to  that  processor.  However,  file 
editor  does  not  access  workspace  of  that  other  processor. 

b.  Edits  files  even  if  already  open  in  another  processor.  However,  the 
file  editor  must  provide  for  consistent  usage  (Chapter  6)  of  time- 
shared  files. 

c.  Edits  records  using  syntax  standard  among  similar  line-editing 
capabilities  in  other  processors. 

d.  Extracts  substrings  from  records  by  character  position(s),  free-fo»‘m 
fields,  user  defined  format,  and  field  name  in  user  specified  record 
structure?  it  can  use  these  in  relational  operations,  in  string 
expressions,  in  numeric  conversion  and  arithmetic  operations,  and  for 
generating  file  names. 

e.  Inserts  new  records  or  deletes  old  ones  at  accessed  location. 

f.  Displays  accessed  record,  extracted  substrings,  and  computations  on 
user  terminal  or  on  output  files.  Display  can  be  conditioned  on 
extracted  or  other  computed  data,  and  formatted  as  desired  by  user. 
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g.  Can  copy  files  to  tape^  or  tape  to  files;  can  name  and  rename  files; 
can  dcleP:  unwanted  files;  can  Gonpatenate  files;  can  insert  one  file 
within  another. 


17.7  MANAGEP^IENT  DATA  AND  STATUS  REPORTING 


Performance  measurement  in  this  section  refers  to  managemerit  gauges 
of  computer  software  producribn,  rather  than  efiiciency  metrics  on  the 
software  itself.  However,  the  quality  of  the  dielivered  product  iu  certainly  an 
important  aspect  of  performance,  and  so  the  measurement  of  performance 
must  not  exclude  quality  as  a performance  factor.  Therefore,  in  this 
context,  peiformanee  measurement  may  be  reduced  to  the  measurement  of 
the  capacity  of  a software  development  team  to  produce  working, 
documented  software,  together  with  qualifying  rneasurements  of  cost,  time, 
and  quality  of  product.  This  function  is  closely  coordinated  with  the  ability 
of  software  management  to  estimate  costs,  manhours,  and  schedules,  to 
assess  manpower  skills  and  required  areas  of  specialization,  and  then  to 
exercise  measures  of  control  over  the  emerging  quality  of  product 

Basic  to  the  establishment  of  such  measurements  is  the  establishment  of 
standards,  languages,  and  software  production  techniques,  as  discussed 
earlier  in  this  work.  Once  this  is  done,  a conceptual  procedure  for 
performance  measurement  is  not  difficult  to  hypothesizes 

a.  List  desirable  performance  qualities  that  are  also  measurable. 

b.  Develop  a mapping  of  performance  units  into  a uniform  scale  of 
merit 

e.  Measure  performance  and  normalize  (i.e.,  convert  to  a unitless  scale). 

d.  Compute  grade  based  on  some  formula  (say,  as  a weighted  sum  of 
scores). 

The  point  of  view  here  is  that  Science,  teehnolo^,  industry,  and 
commerce  are  based  on  the  ability  to  measure  things  or  phenomena, 
describe  the  results  in  numerical  terms,  make  comparisons,  and  make 
decisions  based  on  these  comparisons. 

The  hypothetical  method  given  above  is  not  without  fault;  associating 
value  with  measurement  is  often  ven^  subjective.  But  measured  quantities 
need  not  be  taken  literally  as  absolutes  in  order  to  provide  management 
with  a useful  took  Indicators  of  trends  may  often  be  just  as  useful  to  a 
manager  as  knowing  the  causal  relationship  basing  the  measurements, 

The  ability  to  assess  the  performance  of  a software  producer— individual 
or  group— is  basic  to  estimating  costs  and  time  and  to  exercising 
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corresponding  control  over  the  production  process*  At  the  same  time,  the 
ability  to  measure  performance  will  not,  of  itself,  provide  good 
management  teclmique*  It  will,  however,  permit  responsible  m^agement 
to  measure  difiereiices  betw^n  alternatives  and  to  react  accordingly.  The 
software  manager  assumed  here  will,  therefore,  be  assumed  to  be  already 
competent  in  his  job,  even  without  automated  support;  any  automated 
capability  he  is  provided  should  merely  aid  him  in  performing  that  Job. 

Eveiy  manager  has  an  established  need  co  collet  and  manipulate  data 
directly  concerned  with  performance  and  to  use  these  data,  or  relationships 
among  data  items,  in  the  performance  of  his  job^  If  collected  into  a data 
base  that  can  be  accessed  and  queried  by  a computer,  then  there  needs  to 
be  a welMefiiied,  eflfeetive  means  by  which  its  users  perceive  and  interact 
with  that  data  base.  The  form  of  this  interface  between  the  data  base  and 
the  manager  is,  thus,  particularly  vital  to  the  utility  of  that  system, 

17.7.1  The  Management  Forms  Approach 

The  data-base/end-user-facility  interface  recommended  by  the 
CODASYL  End  User  Facility  Task  Croup  [41]  is  one  based  on  the  -‘forms 
approach'*  to  da.ta  base  operations.  The  essence  of  this  approach  is  that  it 
enables  the  manager,  among  others,  to  think  of  and  view  the  content  of  the 
software  management  data  base  as  a series  of  two  dimensional  forms 
contained  in  files  and  folders  (Figure  17-15). 

There  are  three  subclasses  of  forms  that  may  he  identifi^;  perception 
forms,  user  forms,  and  worksheets  (Figure  17-16).  Perception  forms  form  the 
level  of  access  between  the  management  user  and  the  software  management 
data  base;  all  queries  of  the  data  base  are  eventually  effected  using 
perception  forms,  so  that  the  manager  need  never  be  aware  of  the  actual 
data  base  structure.  The  programs  and  subroutines  forming  this  level  of 
access  are  intended  to  be  standard  across  all  developments,  with  interfaces 
defined  and  maintained  by  the  secretariat  function.  Each  project,  however, 
has  its  own  data  base,  and  defines  maintains  that  data  base. 


User  forms  are  mappable  to  and  from  perception  forms,  but  not  directly 
to  and  from  the  data  base  itself.  One  defining  a user  form  need  not  have 
knowledge  of  the  data  base  structure^  only  the  structure  of  the  perception 
forms.  User  forms  are  meant  to  be  project-special,  the  software  for 
processing  such  forms  being  provided  by  that  individuaL  project,  or  by  the 
secretariat  as  a service. 

Worksheets  are  the  means  by  which  the  end  user  extracts  information 
from  other  forms  and  operates  on  this  information  in  a '‘scratchpad*' 


i 


Figure  17*1$.  Tlie  ehcl'tiser  tedltty  forms  approach  analogy 
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fashion.  Worksheets  are  programmed  by  each  project  or  project  manager  as 
a temporary  device  for  assembling  and  viewing  data  relative  to  team 
performance. 


17:7.2  Management  Information  Processing 

Generation  of  performance-monitoring  reports  extracts  information  from 
both  the  programming  data  base  and  the  management  data  base  proper.  A 
management  information  system  to  accomplish  the  task  needs  to  be  flexible 
to  meet  the  needs-range  of  its  users  and  adaptable  to  reporting  the  status 
indicators  of  interest.  Without  value-to-measurement  mappings*  usage  will 
probably  be  aimed  primarily  at  spotting  trends  or  making  projectioas  of 
costs,  schedules,  and  the  like. 


216  Standard  Software  Production  System  [CHAP,  17 

TypiGalinformation  (foms)  of  interest  might  include 

• Tier  chart  and  stub  status,  perhaps  gauged  relative  to  architectural 
baseline  design 

• Actual  eostSj  eompiiter  usage,  and  manpower 

• Programming  transaction  statistics 

• Lines  of  code,  datai  documentation,  etc. 

• Schedule  and  PERT  status  and  projections 

• Decision  Log 

• List  of  action  items,  problems,  anomalies,  and  dispositions 

• Standards  waiver  log 

• Work  breakdown  structure  and  performance  status 

• Configuration  management  data 


The  software  to  implement  management  forms  constitutes  what  may  be 
termed  a ’^management  information  processor,”  and,  ihasmueh  as  it  is 
manipuSatable  (programmable)  by  the  user,  it  forms  a “program 
management  language*”  Users  will  he  dealing  with  all  five  classes  of  the 
data  object  hierarehy  shown  in  Figure  17-15:  items,  groups,  forms,  folders, 
and  files.  They  will  require  naming  and  sebc^tion  capabilities  that  direct  the 
system  to  define  and  access  occurrences  cf  data  in  these  classes.  The  class 
hierarchy  makes  this  potentially  very  easy.  For  example, 

TRANSACTION.  SMITH.  RUNTIME*  MAY.  1 6 

could  refer  to  the  TRANSACTION  file,  SMITH  folder,  runtime  form,  may  group, 
16th  (day)  items. 


Operations  on  fonns  to  create  worksheets  may  need  to 

• Define  worksheet  fonnat  and  hierarchy 

• Update  management  base 

• Locate  materials  for  query 

• Sort/merge/extract  material 

• Move,  copy  materials  within  base 

• Remove  materials  from  base 

The  user  of  such  a system  must  be  willing  to  understand  that  his  view  of 
the  data  is  largely  predefined  (by  the  secretariat)  and  that  there  is  a finite 
set  of  such  operations  that  he  may  invoke.  Judiciously  chosen,  however. 
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th^e  can  make  the  perfonnanGe  evaluation  task  a much  more  informed 
process.  The  need  for  voluminous  reports  on  a periodic  basis  may  be 
drastically  reduced,  since  managers  can  access  the  performance  monitors  in 
a timely  manner  and  locate  specific  data  of  interest  already  in  a reportdike 
format 


17.8  CONCLUSION 


I began  this  work  with  a promise  to  provide  formal  disciplines  for 
increasing  the  probabili^  of  securing  software  that  is  characferizable  by  a 
high  degree  of  initial  correctness,  readability,  and  maintainability,  and  to 
promote  practices  that  aid  in  the  consistent  and  orderly  development  of  a 
total  software  system  within  budgetaiy  and  schedule  constraints.  Perhaps 
the  initial  chapters  in  this  volume  read  as  though  the  programmer  himsdf 
were,  thus,  to  become  the  programmed,  a creative,  but  regimented, 
automaton. 

Rather,  the  standards  given  represent  a disciplined  approach  adaptable  to 
the  development  of  production  software  of  almost  any  ilk.  That  disciptine 
begins  with  the  understanding  why  top-down,  hierarGhic,  structured, 
modular  methods  offer  the  potential  for  programming  improvement.  It 
continues  with  the  realization  that  the  potential  for  improvement  is  no 
guarantee,  but  that  justifiable  adaptations  or  relaxation  of  standards  on  a 
case-by-case  basis  may  be  necessary  and  are  not  proscribed.  It  culminates  in 
practice  when  the  programming  environment  supports,  and,  indeed,  fosters, 
the  use  of  these  standards. 

The  standard  production  system  I have  envisioned,  more  than  described, 
in  these  final  pages  was  meant  to  aid  and  abet  the  software  engineer  and  his 
manager,  and  to  profit  his  organization  in  consequence.  Volumes  could,  and 
may  yet,  appear  setting  forth  requirements,  specifications,  and  usage  of  that 
system. 

I would  have  liked  to  have  addressed  management  data  Gollection  arid 
reporting  in  more  detail,  as  I would  also  with  features  for  source  data 
maintenance,  data  security,  documentation  support,  langiiage  design,  and 
many  more  topics  so  necessary  in  a production  system  well  enough 
integrated  and  coordinated  to  be  termed  * 'Standard/*  However,  the  system 
philosophy,  if  not  the  detail,  I think,  comes  through^ 

Before  this  monograph  was  begun,  the  development  of  quality  software 
was  truly  an  art,  well-mastered  by  only  a few  of  its  many  practitioners.  The 
methodology  reported  in  these  pages  has,  more  than  once  since,  produced 
evidence  that  production  programming  may  even  now  be  a passing  art 
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fdrim*  Its  final  passage  will  not  be  lamented,  however,  for  it  is  being 
replaced  by  a more  useful  and  eflFective  engineering  discipline.  Whereas  ait 
forms  are  generally  mastered  by  a few  but,  perhaps,  appreciated  by  m^y» 
the  engiiieering  discipline  will  be  both  practiced  and  appreciated  by  an 
entire  community  of  ^herents.  With  that  hope,  I bring  this  work  to  a long 
overdue,  but  somewhat  reluctant,  close. 


APPENDIX  A 

GLOSSARY  OF  TERMS  AND 
ABBREVIATIONS 


This  appendix  presents  definitions  of  the  major  concepts  and  terms  as 
used  throughout  this  work.  In  general,  concepts  and  terms  found  in  an 
eveiyday  non-technical  vocabulary  are  not  included;  definitions  given, 
which  may  also  have  a more  general  meaning  outside  the  field  of 
information  processing,  are  herein  oriented  toward  the  more  restricted 
context  pertaining  to  software  production  and  technology.  Where  possible, 
these  definitions  were  made  to  conform  to  the  ANSI  vocabulary  [42]  and  to 
usages  in  Webster's  New  Collegiate  Dictionary  [43]  (oriented  as  above); 
inevitably,  however,  the  definitions  given  may  not  be  the  same  or 
equivalent  to  some  current  usages  in  the  software  industry. 
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Abnormal  Termination«  Termination  of  processing  of  a program  or 
module  within  a program  due  to  fatal  errors  which  require  that  control 
be  diverted  to  a program  recoveiy  mode,  such  as  return  to  the  user  for 
subsequent  decision  making  and  manual  operations. 

Abstraction.  A mechanism  for  hierarchic,  stepwise  refinement  of  detail  by 
which  it  is  possible  at  each  stage  of  development  to  express  only  relevant 
details  and  to  defer  (and,  indeed,  hide)  non-relevant  details  for  later 
refinement 

Abstract  Resource.  Any  commodity  or  available  means  that  may  be 
allocated  toward  the  accomplishment  of  a task,  characterizable  by 
abstractions  in  representation,  manipulations,  and  axiomatization. 

Acceptance  Criteria.  Criteria  that  a set  of  software  must  satisiy  in 
Gonfonh^ce  with  delivery  requirements.  Software  delivered  for  interim 
operations  with  discrepant  items  is  said  to  be  accepted  with  “liens.” 

Acceptance  Tests.  Tests  to  verify  acceptance  criteria  for  program 
cartificatibn. 

Accuracy.  The  degree  of  freedom  from  error;  that  is,  degree  of  conformity 
to  truth  or  to  a rule.  Contrast  with  precision. 

Adaptation.  Modification  of  existing  software  in  order  that  it  may  be  used 
as  a module  in  a program  development,  as  opposed  to  developing 
another  module  for  that  same  purpose. 

Algorithm.  A prescribed  set  of  welWefined  rules  or  processes  for  the 
solution  of  a problem  in  a finite  number  of  steps.  In  principle,  the  steps 
are  sufiiciently  basic  and  definite  that  a human  can  compute  according  to 
the  prescribed  steps  exactly  and  in  a finite  length  of  time,  using  pencil 
and  paper.  Contrast  with  heuristic. 

Alphanumeric.  Pertaining  to  a character  set  that  contains  letters  and  digits 
only.  When  applied  to  identifiers,  it  usually  requires  that  the  first 
character  be  a letter.  A “spacer”,  such  as  the  underscore  character,  is 
sometimes  also  admitted  into  the  alphanumeric  set  for  identifiers. 

Arbiter.  A mechanism  for  effecting  the  mutually  exclusive  use  of  a shared 
resource  among  concurrent  processes. 

Architectural  Design.  Selection  among  major  alternatives  relative  to 
control  logic  and  data  structural  topologies,  module  coupling  modes, 
clocking,  protocols,  resource  allocation  strategies,  etc.,  to  that  degree  of 
detail  which  provides  convincing  evidence  of  production  feasibility  and 
which  permits  cost  and  schedule  estimates  of  predefined  accuracy. 

Assessment  of  Correctness.  The  process  of  judging  that  a program  (or  part) 
is  correct,  based  on  a partial  demonstration  of  its  actual  or  envisioned 
behavior.  Demonstration  may  range  from  rigorous,  formal  mathematical 
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proof  to  informal  rationale,  or  from  exhaustive  testing  to  mere  program 
checkout 

Audit  A formal  or  offictal  examination  that  attests  to  the  conformity  (or 
nonni^onformily)  between  two  supposed  equivalent  entities,  according  to 
a predefined  set  of  rules* 

Bottom-up  Principle*  A synthesis  from  concrete,  low-level  details  by 
stepwise  integration  into  higher-level  capabilities  or  more  abstract 
concepts  as  a method  for  solving  a problem* 

Calibration  Error*  An  error  purposely  inserted  into  a program  to  serve  as  a 
means  for  gauging  the  completeness  of  testing  to  uncover  indigenous 
errors. 

Certificatipn*  A formal  or  official  attestment  that  acceptance  criteria  have 
been  met,  or  have  been  met  subject  to  a noted  set  of  liens  for  later 
removal 

Checkout*  Informal  validation  of  a program  or  a part  of  a program  by 
members  of  the  development  team,  once  the  item  has  been  suGcessflilly 
compiled  (or  assembli^),  by  running  a series  of  tests.  When  such 
validation  is  performed  only  visually,  the  activity  is  referred  to  as  “desk 
checking*" 

Ck)der.  An  individual  mainly  involved  with  writing  but  not  designing  a 
computer  program. 

Coding.  The  activity  of  expressing  the  steps  of  a given  algorithm  in  a 
computer  language  (or,  perhaps,  more  than  one  language).  A unit  is  not 
qualified  as  “coded"  until  compiled  (or  assembled)  and  all  syntax  errors 
removed. 

Cohesion  or  Module  Strength.  A relative  measure  of  the  strength  of 
relationships  among  the  intemal  components  of  a module  insofar  as  they 
contribute  to  the  variation  in  assumptions  made  by  the  outside  program 
concerning  the  role  the  module  plays  in  the  program*  Invariant 
assumptions  about  a module  indicate  high  strength. 

Competing  Characteristics.  A set  of  factors  that  relate  to  the  final  quality 
of  a piece  of  software,  but  that  may  conflict  or  compete  for  project  or 
machine  resources.  These  may  be  ordered  in  priority  to  form 
implementation  guidelines. 

Complexity  of  a Program.  The  minimum  {conceptual)  length  of  the  “proof 
of  correctness"  of  a program,  relative  to  a particular  set  of  availabie 
methods  for  performing  the  “proof  of  correctness,"  such  as  formal 
mathematical  rigorous  theorem  proving,  informal  (but  complete) 
reasoning,  exhaustive  testing,  etc. 
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Concurrent  Processes.  The  siimiltaneous*  overlapping,  or  time-interleaved- 
operation  execution  of  two  or  more  processes  in  a single-  or  multiple- 
processing  system. 

Concurrent  Production  PFinciple.  A method  in  which  the  formal 
production  of  software  proceeds  with  concurrent  aetivities  among  design^ 
coding,  testing,  and  documentation. 

Confidence  Level.  The  probability  that  a given  statement  concerning  a set 
of  random  variables  or  a segment  of  a random  process  will  be  upheld,  if 
tested. 

Connections^  Connectivity.  The  set  of  assumptions  the  rest  of  a program 
makes  about  a module  (or  other  program  segment).  Modules  have 
connections  in  control,  in  data,  and  in  services  (functions)  performed. 
Connectivity  increases  with  the  number,  type,  and  variability  of  such 
assumptions. 

Consistency.  A program  quality  which  assures  that  the  results  of  executing 
a program  are  repeatable  in  a practical  sense,  in  spite  of  any  logical 
errors  which  may  he  present  in  the  program. 

Control  Data,  Data  that  selects  an  operating  mode  or  submode  in  a 
program,  directs  the  sequential  flow,  or  othenvise  directly  influences  the 
function  of  a program. 

Control  Logic,  The  topological  connectivity  and  the  set  of  conditions  that 
together  govern  the  apparent  sequencing  of  operations  within  a process 
(or  among  concurrent  processes).  Control  logic  is  often  displayed  by 
means  of  a flowchart. 

Correctness.  Agreement  between  a program  s total  response  and  the  stated 
response  in  the  functional  specification  (functional  correctness),  and/or 
between  the  program  as  coded  and  the  programming  specification 
(algorithmic  correctness). 

Correctness  Proof.  Demonstration,  however  made,  that  the  response  of  a 
program  agrees  with  its  hinctional  and  programming  specifications. 

CRISP,  Control-flestriGtive  /nstmetions  for  Structured  Programming.  A set 
of  keywords  used  to  introduce  structured  control  flow  into  an 
unstructured  language.  Also  used  as  control  sublanguage  of  CRTSP- 
FLOW  (flowcharts)  and  CRISP-PDL  processors, 

Critical  Region.  A region  within  a process  in  which  a shared  resource  must 
only  be  accessed  on  a mutually  exclusive  basis  for  program  consistency 
and  correctness. 

Data.  Representations  of  measurements,  observations,  facts,  statistics,  or 
derived  quantities,  either  actual,  believed,  or  assumed,  in  a form  suitable 
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for  communicatibn,  reorganization,  storage,  retrieval,  processing,  and 
dissemination*  Contrast  with  information. 

Data  Base.  A cblleciion  of  interrelated  data  items^  usually  stored  together, 
to  serve  one  or  more  applications  by  end  users.  As  a goal,  the  data  base 
has  little  (or  controlled)  redundanGy^  is  stored  so  as  to  be  independent  of 
the  usages  made  of  its  contents,  yet  is  stored  for  optimal  e^iency  by 
such  applications,  and  is  capable  of  being  subjected  to  a common  and 
controlled  approach  when  adding  new  data  or  when  modifying  or 
retrieving  data  existing  within  the  data  base.  A **data  base  system”  is  a 
collection  of  separately  structured  data  bases  united  by  regulated 
interaction  to  form  an  organized  whole. 

Data  Base  Administrator.  The  custodian,  an  individual  or  organization,  of  a 
data  base  or  data  base  system.  The  data  base  administrator  does  not  own 
the  data  nor  control  its  use;  however,  the  data  base  administrator  does 
control  the  structure  and  the  modes  of  access  of  the  data  base(s),  checks 
authority  to  use  data  in  the  base(s),  and  is  responsible  for  the  security  and 
integrity  of  the  data  base(s). 

Data  Flow  Diagram.  A graphic  representation  that  displays  the  paths  of 
data  through  a problem  solutioDi  It  defines  the  major  or  essential  features 
of  processing  as  well  as  the  various  media  used. 

Data  Structure.  A formalized  representation  of  the  ordering  and 
accessibility  relationships  among  stored  data  items,  without  regard  to  the 
actual  storage  configuration,  as  characterized  by  data-item  ^^es,  ranges 
of  values,  and  scope  of  activity,  suitable  for  communication,  interpreta- 
tion, or  processing  by  humans  or  automatic  means. 

Deadlock.  That  condition  in  which  concurrent  processes  are  each  awaiting 
conditions  that  can  never  hold.  Also  called  "stalemates”  or  “deadly 
embraces.”  Deadlocks  occur  when  each  of  the  deadlocked  processes  is 
waiting  for  tike  others  to  act,  but  each  is  unable  to  do  so. 

Debugging.  Detection,  location,  and  repair  of  inconsistencies  between  the 
program  response  and  its  functional  or  programming  specificatioa  A 
program  or  procedine  is  said  to  be  debugged  if  no  known  anomalies  are 
present 

Decision  Table.  A table  of  all  or  selected  contingencies  to  be  considered  in 
the  description  of  a problem  or  the  specifiGatiori  of  a solution,  together 
with  actions  to  be  taken  in  each  combination  of  contingencies.  Also 
called  “decision  logiG  tables.” 

Design.  That  activity  which  defines  program  data  structures  and  logical 
algorithms  in  response  to,  and  conforming  with,  the  software  functional 
specificatiba  It  consists  of  describing  the  organizatioa  data  manipula- 
tions, I/O  procedures  and  formats,  etc.,  carried  to  a level  of  detail 
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sufficient  for  coding  and  operationat  implementation.  Also^  the  word 
"design*'  may  refer  to  the  structure  of  the  program  resulting  from  the 
design  activity,  and,  therefore,  to  the  software  programming  specifica- 
tion. Devlopment  of  the  software  functional  specifications  is  sometimes 
called  "functional  design." 

Deque.  A data  structure  (Double-Ended  QUEne,  pronounced  "deck**)  that, 
together  with  its  access  functions,  model  operations  with  a linear  list  in 
which  insertions  and  deletions  can  be  made  at  either  end  of  the  list 

Development.  Thai  process  by  which  new  software  comes  into  being  as  a 
process  of  design,  rather  than  by  a process  of  modification.  It  includes 
both  the  architectural  and  implementation  phases. 

Document.  A m€^dium  and  the  information  recorded  on  it  for  human  use; 
by  extension,  any  such  record  that  has  permanence  and  that  can  be  read 
by  mail  or  machine.  In  this  latter  sense,  a source  code  listing  is  a 
document 

Documentation.  The  creating,  collecting,  organizing,  recording,  storing, 
citing,  and  disseminating  of  documents  or  the  descriptive  material  within 
documents. 

Documentation  Level.  Specification  of  the  degree  of  detail  (A,B,C,D)  and 
the  format  quality  (1,2,34)  for  a particular  item  of  documentation. 

Engineering.  Applied  science  concerned  with  the  utilization  of  raw 
materials,  products  of  technology,  and  physical  laws  for  supplying  human 
needs.  A profession  characterized  by  the  propensity  to  solve  technologi- 
cal  and  related  problems  with  given  constraints  in  an  organized, 
responsible  way. 

Error.  Any  discrepancy  between  a computed,  observed,  or  measured 
quantity  and  the  true,  specified,  required,  or  theoretically  correct  value 
or  condition. 

Flag,  A simple  data  stnicture  that  directs  the  flow  of  control  in  a program. 
If  it  has  a range  of  only  two  values,  it  is  sometimes  called  a "boolean**  or 
"switch.”  Flags  used  solely  to  permit  a program  to  have  structured 
control  flow  are  called  structure  flags. 

Flowchart.  A graphical  representation  for  the  definition,  analysis,  or 
solution  of  a problem  in  which  symbols  are  used  to  represent  operations, 
fn  this  text,  a flowchart  describes  the  logic  and  sequence  of  operations  in 
a module  algorithm,  drawn  to  conform  to  ANSI  standards  (Appendix  B). 

Function.  Mathematically,  a mapping  between  an  input  domain  and  an 
output  range,  in  which  each  input  has  but  a single  image  in  the  output 
Therefore,  in  a program,  a function  performs  a transformation  or  service 
as  determined  by  its  input.  However,  some  modules  that  are  not 
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functions  in  the  mathematical  sense  (such  as  random-number  generators 
and  simulators  of  finite  automata)  are  nevertheless  described  by 
“ftmctional”  specifications*  because  they  perform  wcU-defined  actions  as 
defined  by  finite-state  machines.  See  procedure. 

Functional  Requirements  Document  (FRD).  A document  stating  the 
essential  technical  features  of  a needed  data  processing  capability*  along 
with  technical  constraints  and  conditions  to  be  met,  and  criteria  for 
acceptable  delivery  that  can  be  appended  to  or  made  a part  of  the  SRD, 

Functional  Testing,  Validation  of  program  “functional  correctness’*  by 
execution  under  controlled  input  stimuli.  This  testing  also  gauges  the 
sensitivity  of  the  program  to  variatioas  of  the  input  parameters. 

Hardest-Out  Principle.  The  building  of  a system  beginning  with  that  part 
which*  in  the  final  analysis,  would  have  proved  to  possess  the  highest  risk 
to  programming  if  not  performed  first.  At  each  subsequent  step,  the  next 
a posteriori  most  eritical  part  is  added,  until  the  entire  software  package 
is  completed. 

Heuristic.  An  exploratory  method  of  problem  solving  in  which  solutions 
are  discovered  by  evaluation  of  the  progress  made  toward  the  final  result. 
Contrast  with  algorithm. 

Hierarchy.  A stnicture  by  wliich  objects  or  classes  of  objects  are  ranked 
according  to  some  subordinating  principle  or  set  of  principles.  One 
common  representation  of  a hierarchy  is  the  directed  tree-graph,  in 
which  the  root  node  heads  the  hierarchy*  and  all  other  objects  are  ranked 
by  order  into  levels  of  subordination,  If  a single  subordinating 
relationship  governs  the  hierarchy,  it  is  said  to  be  unordered;  otherwise  it 
is  ordered. 

HIPO.  //ierarchic  /nput-Processing-Oiitput  descriptions.  These  descrip- 
tions, often  viewed  in  the  forms  of  graphics  (so  called  HIPO  charts),  are 
used  chiefly  to  express  requirements  and/or  functional  specifications  for 
programs,  routines,  etc. 

Identifier.  A symbol  whose  purpose  is  to  identify,  indicate,  name,  or  locate 
a data  stmeture  or  procedure  entry  point. 

Implementation.  That  process  by  which  an  architectural  design  is  turned 
into  a delivered  program.  It  includes  the  detailed  functional  and 
procedural  design,  coding,  testing,  and  documentation  necessary  to  meet 
program  requirements*  either  for  new  or  modified  software. 

Indigenous  Error.  An  error  existing  in  a program  (specification  does  not 
agree  with  performance)  that  has  not  been  inserted  for  calibration 
purposes. 
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Inductive  Assertion.  An  invariant  predieate  appearing  within  a procedure 
iteration.  Usually  placed  just  following  the  loop-GolleGting  node,  these 
predicates  are  used  as  an  aid  toward  proving  correctness. 

Information.  A representation  of  knowledge,  intelligence,  or  other 
meaningful  data  in  a form  that  can  be  used  to  cause  or  modify  the 
purposeful  actions  of  humans  or  machines,  perhaps  as  the  result  of 
proper  organization,  analysis,  and  presentation.  Contrast  with  data. 

Information  Structure.  A representation  of  the  elements  of  a problem  or  of 
an  applicable  solution  method  for  a problem,  insofar  as  its  information 
base  is  concerned. 

Information  System.  An  assemblage  of  methods,  techniques,  procedures* 
progranis,  or  devices  that  sense,  convey,  store,  process,  retrieve,  or 
disseminate  information,  united  by  regulated  interaction,  to  acGomplish 
an  organized*  purposeful  task. 

Information  Systems  Technology.  The  body  of  knowledge  and  physical 
phenomena  that  constitute  ah  applied  science  oriented  toward  the 
industrial  usage  of  information  systems. 

Instructions.  The  repertoire  of  a language  or  (virtual)  machine. 

Integration.  The  combination  of  subunits  into  an  overall  unit  or  system  by 
means  of  interfacing  in  order  to  provide  an  envisioned  data  processing 
capability. 

Interface.  When  applied  to  a module,  that  set  of  assumptions  made 
concerning  the  module  by  the  remaining  program  or  system  in  which  it 
apears.  Modules  have  control,  data,  and  services  interfaces. 

Interface  Testing.  Validation  that  a module  or  set  of  modules  operate 
within  agreed  interface  spccifiGations  to  assure  proper  data  and  logical 
communications. 

Interrupt.  Any  stopping  of  a process  in  such  a way  that  it  can  be  resumed. 
A particular  type  of  interrupt  is  the  ‘"trap.” 

Invocation.  The  linking  to  or  insertion  of  a procedure  body  by  means  of  a 
named  reference  within  a procedure.  Subroutine  linking  is  sometimes 
referred  to  as  a “call/'  Code  insertion  is  referred  to  as  a “macro  call." 

Level.  The  degree  of  subordination  in  a hierarchy.  See  also  level  of  access 
and  documentation  leveL 

Level  of  Access.  A set  of  functions,  macros,  subroutines,  etc.,  that  access  a 
particular  data  structure  or  type  of  data  structure,  through  which  all 
accesses  to  that  structure  or  fype,  except  tiiose  within  the  functions,  etc., 
must  pass.  Also  called  • -clusters''  and  “Pamas  modules." 
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lexical  Binding;  Location  of  components  constituting  a module  physically 
together. 

Lien.  A charge  upon  some  discrepant  software  item  in  the  form  of  a debt 
or  du^  later  to  be  redeemed  or  otherwise  satisfied.  Usually  this  term 
refers  to  the  deliveiy  of  software  in  some  usable  form  but  requiring  the 
removal  of  discrepancies  (program  or  documentation)  in  order  to  be 
complete. 

Logie  Error.  An  error  in  a program  procedure,  as  opposed  to  an  error  in  a 
program  functional  specification. 

Look-Ahead  Design  Principle.  The  principle  by  which  a baseline  or 
preliminary  design  (or  program  architecture)  is  developed,  which 
identifies  and  sketches  the  key  details  of  the  remaining  work  to  be  done 
to  assure  that  the  subsequent  detailed  implementation  will  be  proper 
when  viewed  in  retrospect. 

Macro.  A body  of  te^  substituted  directly  for  a statement  or  portion  of  a 
statement  recognized  to  be  of  a proper  form.  Macro  invocations  may 
transmit  parameters  for  substitution  or  for  processing  before  substitution 
into  the  code  body  that  replaces  the  invocation. 

Maintenance.  Alterations  to  software  during  the  post-delivery  period  in  the 
form  of  sustaining  engineering  or  modifications  not  requiring  a 
reinitiation  of  the  software  development  cycle. 

Maximum  Likelihood  Estimator.  That  function  of  observed  data  that 
estimates  an  unknown  parameter  of  a known  or  assumed  probability 
distribution  function  as  the  value  that  maximizes  the  probability  (density) 
function  on  the  observed  data. 

Mode,  A way  of  operating  a program  to  perform  a certain  subset  of  the 
functions  that  the  entire  program  can  perform^  as  selected  by  control 
data  or  operating  conditions.  Often,  the  mode  of  a program  will  be 
defined  as  program  states,  with  transitions  annotated  to  delineate  events 
causing  the  passages  between  modes  of  operation. 

Modification.  The  process  of  altering  a program  and  its  speeificatibn  so  as 
to  perform  either  a new  task  or  a different  but  similar  task.  In  all  cases, 
the  functional  scope  of  a program  under  modification  changes.  Contrast 
with  adaptation  and  sustaining  engineering; 

Module.  Identifiable  subportions  of  a program  composed  of  instnietions  or 
statements  in  a form  acceptable  to  a computer  prepared  to  achieve  a 
certain  result.  They  are  charaGterized  by  lexical  binding,  identifiable 
proper  boundaries,  named  access,  and  named  reference.  The  word 
may  apply  to  a subprogram,  subroutine,  routine,  program, 
macro,  or  function.  A ‘^compile-module”  is  a module  or  set  of  modules 
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that  are  discrete  and  identifiable  with  respect  to  compilings  combining 
with  other  units^  and  loading. 

Monitor.  A level  of  access  on  a shared  resource  in  a program  with 
concurrent  processes,  including  the  means  for  arbitration  of  that 
resource, 

Muhiprocess^  The  simultaneous  or  concurrent  execution  of  separate 
sequences  of  actions  by  multiple  hardware  processors. 

Multiprograinming,  The  time-shared  use  of  a processor  in  which  two  or 
more  programs  or  program  modules  execute  by  interleaving  operations 
in  time. 

Named  Module.  Modules  which  can  be  invoked  by  name  (named  access) 
and  which  internally  may  invoke  submodules  by  name  (named  reference). 
Such  invocation  in  the  flowcharted  design  is  denoted  by  the  method  of 
“striping”  the  flowchart  symbol 

Nesting.  The  recursive  application  of  the  imbedding  of  structures 
(procedural  or  data)  into  a hierarchy  of  structural  levels  of  definition. 

Operating  System.  A system  of  routines  and  services  that  monitors, 
controls,  allocates,  de-allocates,  and  manages  the  execution  of  applica- 
tions programs  and  other  systems  routines  and  their  usages  of  system 
resources. 

Operation.  A well-defined  finite-time  execution  within  a program, 
performing  a time-independent  function  based  cn  its  input 

Operator,  (a)  In  a program,  a function  or  chavacteristic  action  on  data 
items  (operands),  (b)  In  computer  utilify,  an  individual  who  monitors  or 
manipulates  peripheral  devices  and  innut/output  streams  during  the 
exeGUtjon  of  a program  or  system. 

Opossum.  Any  of  a family  of  small  American  marsupials^  chiefly  nocturnal, 
largely  arboreal,  and  almost  omnivorous.  When  frightened,  it  feigns 
death  [43j. 

Parallel  Processes.  The  simultaneous  or  concurrent  execution  of  two  or 
more  processes  in  devices  such  as  multiple  arithmetic  units,  logic  units, 
or  device  channels. 

Paranormal  Tenhination,  Unstructured  escapes  (in  control)  from  a module 
in  response  to  normal  events  or  conditions.  Compare  with  abnormal 
termination.  Modules  haying  paranormal  terminations  may  yet  exhibit  a 
form  of  structured  control  flow,  if  properly  configured  into  "‘paranormal 
extensions”  of  structured  programming. 

Perception  Form^  The  level  of  access  between  end  users  and  a 
computerized  data  base  system  in  an  end-user  facility  approach  to  data 
base  operations.  All  user  operations  with  the  data  base  are  eventually 
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effected  using  perception  forms,  as  end  users  never  need  be  aware  of  the 
actual  storage  structure  of  the  data  base»  Such  forms  are  usually  standard 
across  a number  of  eiidruser  groups  accessing  the  same  or  similar  data 
bases;  Perception  forms  are  defined*  programmed*  and  maintained  by  a 
data  base  administrator  function. 

Performance.  A measure  of  the  capacity  of  an  individual  or  team  to  build 
software  capabilities  in  specialized  or  generalized  contexts.  Performance 
distinguishes  between  work  and  effort,  as  it  includes  productivity  as  one 
component  of  its  measure.  However,  performance  also  measures  quality 
of  work  as  measured  by  other  criteria  as  well,  as  set  forth  in  a prioritized 
list  of  “competing  characteristics**  early  in  development. 

Phase  of  Production.  That  work  related  to  the  completion  of  a specified  set 
of  modules  in  conformance  with  requirements  and  goals.  In  top-down 
developments,  a set  of  modules  that  are  currently  dummy  stubs  becomes 
the  next  implementation  phase. 

Post-order  Traverse  of  a Graph  (Tree).  A method  of  “visiting**  each  node  of 
a tree  or  other  appropriate  graph  in  which  at  each  branching  node  the 
discipline,  'Visit  each  subgraph  emanating  from  this  node  iii  leftmost 
order”  and  then  “visit  this  node,”  is  imposed  recursively.  The  meaning  of 
“visiting**  is  that  particular  action  taken  while  at  a given  node. 

Precision.  A measure  of  the  degree  of  discrimination  with  which  a quantity 
can  be  stated,  as  opposed  to  accuracy*  which  states  the  degree  to  which 
that  quantity  is  free  from  error. 

Predicate.  A logical  proposition  or  assertion  concerning  the  state  of  a 
program  at  a given  point,  having  either  a triie  or  false  value.  Goncerning 
program  correctness,  all  such  assertions  must  be  axioms  or  proved  true. 

Pre*order  Traverse  of  a Graph.  A method  of  “visiting**  each  node  of  a tree 
or  other  appropriate  graph  in  which  at  each  branching  node  the 
disciptine,  “visit  this  node”  and  then  ‘Visit  the  subgraphs  emanating  from 
this  node  in  leftmost  order,*’  is  imposed  recursively.  The  meaning  of 
“visiting"  is  that  particular  action  taken  while  at  a given  node. 

Procedure.  The  course  of  action  taken  for  the  solution  of  a problem.  A set 
of  statements  forming  an  algorithm.  Procedures  can  be  programmed  as 
subprograms,  subroutines,  macros,  or  functions.  A procedure  may  not, 
perhaps,  always  compute  a function  in  the  mathematical  sense,  but, 
nevertheless,  the  term  “function**  is  often  used  to  describe  the 
characteristic  action  of  such  modules. 

Procedure  Design  Language.  A language  for  specifying  algorithms  in 
ordinary  Eriglish  or  other  language  not  to  be  compiled.  Keywords  usiially 
appear,  so  as  to  format  text  and  conform  the  specifications  into  a 
structured  form.  Also  called  a “Program  Definition  Language”. 
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Process.  A sequence  of  operations  executed  one  at  a time.  Two  process^ 
are  then  concurrent  if  their  operations  can  overlap  or  interleave 
arbitrarily  in  time. 

Production.  That  portion  of  a sofbvare  implementation  that  has  to  do  with 
the  generation  of  code  and  documentation  and  the  checkout  for 
correctness  by  production  personnel.  Production  programming  is 
characterized  by  the  application  of  tradeoffs,  known  algorithms,  and 
state-of-the-art  solution  methods  toward  software  generation,  as  opposed 
to  programming  performed  to  extend  the  current  state  of  the  art. 

Productivity.  A measure  of  the  rate  at  which  individuals  or  teams  can 
produce  or  have  produced  software  items,  or  can  perform  or  have 
performed  software-related  tasks. 

Program.  A series  of  instructions  or  statements,  in  a form  acceptable  to  a 
computer,  prepared  to  achieve  a certain  result,  to  perform  a specified 
function  within  a subsystem. 

Programming.  A generic  word  sometimes  used  to  describe  the  overall 
process  of  program  design,  coding,  and  testing,  but  often  it  is  used  to 
connote  only  coding  and  checkout. 

Programming  Specification  fPS).  That  portion  of  the  Software  Specifica- 
tion Document  (SSD)  which  sets  forth  descriptions  of  algorithms,  data 
stmetures,  the  modular  definition,  etc.,  in  sufficient  detail  that  the 
program  can  be  coded  without  functional  or  algorithmic  ambiguity. 

Proper  Program.  A program  or  program  segment,  such  as  a subroutine, 
subprogram,  or  function,  which  has  but  one  point  of  entry  (in  control) 
and  but  one  mode  of  exit  (although,  if  a subroutine,  it  may  be  called 
from,  and  return  to,  many  points  in  a program)^ 

Protocol.  A rule  prescribing  the  interface  disciplines  and  correct 
procedures  for  communications  with  a program^  subroutine,  operating 
system,  or  hardware  device. 

Queue.  A data  structure  which,  together  with  its  access  functions,  models 
operations  used  in  first-in  first-out  (FIFO)  list  algorithms. 

Real-Time  Process.  A process  actuated  by  and  acting  in  response  to  an 
external  event  sensed  by  the  computer. 

Reliability  Index.  The  probability  that  a program  or  device  will  perform 
without  failure  for  a specified  period  of  time  or  amount  of  usage. 

Requirement.  A characterization  of  the  essential  features  of  a needed  data- 
processing  capability^  along  with  a set  of  constraints  and  conditions  to  be 
met. 
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^ R^uiFements  Testing,  Executibn  of  a program  under  controlled  conditions 

I to  demonstrate  that  all  stated  or  implied  requirements  and  performance 

^ criteria  have  been  met, 

{ Resource,  Any  commodity  or  availiable  means  that  may  be  allocated  toward 

f the  acGompiishment  of  a task.  In  concurrent  processes,  shared  resources 

are  characterized  as  “devoted”  (allocated  for  mutually  exclusive  use)  or 
I “mutual”  (can  be  engaged  in  simultaneous  operations  under  stated 

I limitations).  Resources  produced  by  one  process  and  consumed  by 

j another  are  said  to  be  “temporaiy  resources”;  other  resources  are 

[ “permanent” 

I Routine,  A program  or  program  module  that  may  have  some  general  or 

frequent  use.  If  a program  module,  then  a routine  always  returns  to  the 
i point  of  invocation  after  execution  (i,e,,  a proper  routine)  or  abnormally 

terminates.  Other  types  of  routines  are  not  discussed  in  this  work. 

Scope,  The  range  within  which  an  identified  unit  displays  itself.  Scope  of 
activity  refers  to  the  boundaries  within  which  a data  structure  or 
program  element  remains  an  integral  unit  Scope  of  control  refers  to  the 
submodules  in  a program  that  potentially  may  execute  if  control  is  given 
to  a cited  module.  Scope  of  error  denotes  the  set  of  submodules  that  are 
potentially  afiPected  by  the  detection  of  a fault  in  a cited  module. 

Secretariat.  A centralized  faciliiy  consisting  of  processing  aids,  libraiy 
materials,  and  production  services  available  to  development  projects,  for 
the  purpose  of  raising  productivity,  enforcing  standards,  arid  monitoring 
progress. 

Semantics.  The  set  of  rules  that  defines  relationships  between  symbols  and 
their  meanings;  in  computer  language,  the  rules  that  define  what  effects 
' are  caused  by  statements  in  the  language. 

I Semaphore.  A shared  data  structure  used  by  concurrent  processes  to  effect 

synchronization,  consisting  of  an  arbitrated  variable  that  contains  the  net 
i number  of  “messages”  sent,  not  yet  received^  and  a queue  that  contains  a 

list  (if  not  empty)  of  processes  currently  waiting  for  a “message,” 

Sequential  Testing  Procedure  (STP),  A procedure  for  searching  a decision 
table  condition  entry  to  determine  which  rule  applies  to  a given  array  of 
answers  to  the  condition  stub.  Thus,  an  algorithm  for  processing  the 
upper  half  of  a decision  table  to  determine  which  nite  is  to  be  activated. 

Side-Effect.  A secondary  effect  due  to  connectivity  among  modules  which, 
therefore,  propagates  in  the  same  mode  as  program  connectionsr  control, 
i data,  services.  Control  side  effects  arise  in  non-proper  programming;  data 

connection  side  effects  arise  in  use  of  COMMON,  external  coupling, 
content  coupling,  and  not  utilizing  the  normal  parameter  passing 
mechanism;  and  service  side  effects  arise  when  the  role  or  action  of  a 
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procedure  vaFies  with  its  application  (as  a result  of  global  variables 
modified,  local  data  modifi^  and  retained,  or  changes  in  hardware 
status)* 

Software.  A computer  program  (or  set  of  programs),  together  with  all 
materials,  procedures,  and  documentation:  concerned  with  the  use, 
operation^  and  maintenanGe  of  a data  processing  capabili^. 

Software  Design  Definition  {SDD).  A document  chiefly  used  to  display  the 
results  of  the  architectiu*al  design  study  and  iiUplications  of  cost, 
schedule,  and  work-breakdown  structures  to  management  or  customers, 
Some  high-level  technical  material,  such  as  that  needed  to  assess  problem 
areas  and  other  concerns  or  to  show  how  requirements  will  be  met,  is 
included. 

Software  Development  Library  (SDL).  A project  internal  facility  for 
interface  and  management  visibility  and  for  software  production 
management  and  control. 

Software  Engineering  Management  The  judicious  use  of  means  to  effect 
and  administer  the  advancement  or  usage  of  information  systems 
teehnolo^.  Software  engineering  management  recognizes  needs,  sets 
goals,  plans  modes  of  accomplishment,  devises  means  for  resource 
allocation,  and  directs  the  approach  taken  in  future  information  systems 
applications  and  in  the  solution  of  problems  associated  with  these 
applications. 

Software  Fun^:tional  Specification  (SFS).  That  part  of  the  Software 
Specification  Document  (SSD)  which  defines  the  end-to-end  functional 
response  of  the  program  in  terms  of  input  stimuli,  program  behavior,  and 
output  contents.  Any  program  that  conforms  to  the  SFS  is  deemed 
fimctiGnally  correct. 

Software  Requirements  Document  (SRD),  A document  chiefly  generated 
by  a customer  or  other  initiator  used  to  display  the  needs,  justifiGation, 
and  estimated  costs  associated  with  the  implemeiitation  of  a data- 
processing  capability.  Some  technical  material,  such  as  that  needed  in 
support  of  the  justification  or  establishment  of  needs,  is  included. 
Detailed  technical  requirements  may  be  appended  dr  included  in  the 
Functional  Requirements  Document  (FRD)  portion  of  the  SRD. 

Software  Specification  Document  (SSD),  The  principal  prcgrain  documen- 
tation produced  by  a development  project,  eonsisting  of  "as-builF* 
Functional  (SFS),  Programming  (PS),  and  Test  SpeGifications. 

Software  Test  Report  (STR).  A report  of  the  tests  and  the  results  of  tests 
performed  in  demonstration  of  delivery  requirements* 
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Specification.  A statement  or  set  of  statements  (documentation)  containing 
a detailed  description  or  enumeration  of  particulars  with  respect  to  the 
function  or  construction  of  a piece  of  software. 

Stack.  A data  structure  that,  together  with  its  access  functions,  models 
operations  used  in  last-in  fiist-out  (LIFO)  list  algorithnis. 

Standard.  That  which  is  set  up  and  established  by  authority,  custom,  or 
general  consent  as  a model,  example,  criterion,  test,  or  rule  for  the 
definition  or  measure  of  quantity,  weight,  extent,  value,  or  quality. 

Strength.  See  cohesion. 

Striped  Module.  A named  module  in  the  program  procedural  design,  so 
called  because  of  the  method  used  to  denote  such  modules  on  a 
flowchart.  Striping  of  a flowchart  symbol  signifies  that  a detailed 
representation  is  either  located  elsewhere  in  the  same  set  of  flowcharts 
(horizontal  striping),  or  else  at  a referenced  location  (vertical  . striping). 

Structure.  May  pertain  to  the  manner  or  form  in  which  something  is 
constructed  or  may  refer  to  the  actual  system  as  constructed. 
Descriptions  of  structure  focus  an  interrelation  of  the  various  parts  as 
dominated  by  the  general  character  or  function  of  the  whole.  Designing 
structure  is  a process  of  identifying,  analyzing,  and  selecting  among 
alternatives  within  design  categories; 

Structured  Program.  As  used  in  this  work,  a program  whose  control  logic 
topology  adheres  to  strict  rules  of  form,  being  composed  of  iterations  and 
nestings  of  a set  of  basic  planar  flowchart  constructions  TFTHENELSE, 
WHILEDO,  DOWHILE,  CASE,  and  sequence  formats,  along  with, 
perhaps,  paranormal  extensions. 

Structure  Flag.  A flag  introduced  into  an  otherwise  unstructured  program 
to  permit  structured  control  flow. 

Structure  Graph.  A graphical  representation  showing  the  control 
connections  between  named  modules.  The  “top”  node  of  the  graph 
represents  the  top-level  main  program  procedure;  lines  from  the  top 
node  to  other  nodes  signify  that  the  corresponding  named  modules 
appear  as  iiivoeations  in  the  top-level  program  procedure,  etC; 

Stub,  Dummy.  Segments  of  temporary  code  that  replace  named  modules 
for  purposes  of  correctness  testing  a program  during  top-down 
construction.  These  are  usually  siinple  procedures  that  merely  test 
interfaces  or  supply  test  inputs  for  an  algorithm  under  test.  The  actual 
procedures  replace  the  dummy  stubs  as  they  are  coivstructed. 

Suave,  (adj)  Blandly  pleasing;  smoothly  polite;  urbane;  polished.  Synonymst 
suave,  urbane,  diplomatic,  bland,  smooth,  politic  mean  ingratiatingly 
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tactful  and  well-mannered  Siiave  specifically  suggests  the  power  to 
encourage  easy  and  frictionless  intercourse  (43]. 

Submodule.  A module  appearing  within  a module  or  invoked  by  a module. 
On  a flowchart,  the  procedure  appearing  within  or  referred  to 
invoked  by)  any  charted  symbol 

Subprogram^  As  used  here,  a module  whose  invocation  appears  but  once  in 
a procedural  specification  of  a program.  Subprograms  may  be  coded  in- 
line, as  a macro  (used  once),  or  so  as  to  be  linked  to  (and  from)  as  a 
separate  procedure  body. 


Subroutine.  A routine  that  can  be  a part  of  a routine^  As  used  here,  a 
subroutine  is  always  a proper  procedure  (one  entry  point,  with  return 
only  to  point  of  invocation),  and  appears  in  more  than  one  invocation  in 
the  program  procedure.  Some  subroutines  may  also  have  abnormal 
terminations. 

Sustaining  Engineering.  Software-related  activities  in  the  post-delivery 
period,  principally  supportive  in  form,  which  keep  that  software 
operational  within  its  functional  specifications;  e.g.,  repairing  faults, 
Gorrectihg  documentation,  removing  liens,  and  estimating  costs  and  other 
resources  required  for  such  tasks^  The  holding  or  keeping  of  software  in  a 
state  of  efficiency  or  validity  despite  interface  fluctuations  in  system, 
subsystem,  or  applications  capabilities. 

Synchronization.  The  scheme  by  which  arbitration  constrains  the  ordering 
of  operations  on  shared  resources  among  concurrent  processes  in  time  so 
as  to  enable  consistency  in  the  program  behavior. 

Syntax.  The  set  of  rules  that  defines  the  valid  input  strings  (sentential 
forms)  of  a computer  language  as  accepted  by  its  compiler  (or 
assembler).  Therefore,  the  structure  of  expressions  in  a language,  or  the 
rules  governing  the  structure  of  a language. 

System.  An  assembly  of  methods,  procedures,  programs,  or  techniques 
united  by  regulated  interaction  to  form  an  organized  whole. 

Testing.  Execution  of  a program  (or  partial  program),  usually  under  a 
controlled  set  of  input  conditions,  program  configurations,  and  input 
stimuli,  performed  in  order  to  observe  the  actual  program  response. 

Tier  Chart.  A tree-graph  representation  of  a program  and  its  named 
modules,  in  which  the  subordination  relation  is  invocation.  Subroutine 
invocation  nodes  occur  more  than  once;  however,  all  but  one  of  these 
nodes  appear  as  leaves  of  the  tree,  and  the  other  forms  the  root  of  the 
subroutine  tier  hierarchy. 
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Top-Down  Principle.  A ^thesis  from  abstract,  high-level  concepts  by 
stepwise  refinement  into  lower-level  concepts  and  details*  as  a method 
for  solving  a problem. 

Topological  Sorting,  An  algorithm  for  listing  the  nodes  of  a directed 
acyclic  graph,  in  which  precedence  in  the  graph  implies  precedence  in 
the  list.  One  such  algorithm  is  the  foUowing:  Locate  a node  having  no 
edges  directed  into  it,  transfer  it  to  the  list,  and  delete  all  edges 
emanating  from  it;  repeat  until  all  nodes  have  been  listed. 

Trap  A special  form  of  program  interrupt:  an  unprogrammed  conditional 
jump  to  a known  location,  automatically  actuated  by  hardware,  with  the 
location  from  which  the  jump  occurred  recorded. 

Tree,  An  acyclic  eonnected  graph.  If  the  tree  has  n ^ 2 nodes,  then  it  also 
has  n — 1 edges.  Every  pair  of  nodes  is  connected  by  exactly  one  path.  As 
used  in  this  work,  the  tree  often  represents  a hierarchy,  in  which  edges 
are  directed  to  denote  a subordinating  relationship  between  the  two 
joined  nodes. 

Type  (Data),  A set  of  attributes  used  to  define  a set  whose  elements  are 
data  structures  and  on  which  an  algebra  is  defined.  Fundamental  types 
are  those  explicit  in  a programming  language.  Fundamental  simple  types 
usually  include  integers  and  reals,  and  fundamental  structures  usually 
include  the  indexed  array. 

User,  An  individual  or  organization  which  normally  supplies  information 
for  processing,  or  which  normally  receives,  interprets,  and  utilizes  the 
output  of  such  processing.  Contrast  with  operator. 

User  Forms.  Forms  mappable  to  and  from  perception  forms  in  an  end-user 
facility  approach  to  data  base  operations,  User  forms  are  standard  v^thin 
an  end-user  group  accessing  a data  base  that  has  been  standardized  over 
even  a wider  set  of  user  groups.  User  forms  are  defined  by  the  end-user 
group,  and  niay  be  programmed  and  maintained  fay  either  the  end-user 
group  or  the  data  base  administrator. 

Vaiidation.  Demonstration  that  a software  item  or  implementatiGn 
conforms  to  its  specification  (whether  the  specification  is  eoi  rect  or  not). 
Validation  attests  primarily  to  Gonformity  with  the  grounds  on  which 
something  is  based,  to  a greater  extent  than  conformity  with  accuracy 
criteria.  Compare  with  verification. 

Verification,  Confirmation  that  a program  has  aecurately  satisfied 
acceptance  criteria,  or  that  a data  transcription  or  other  such  operation 
has  been  accomplished  aecurately.  Verification  primarily  deals  with 
accuracy  (freedom  from  error)  to  a greater  extent  than  conformance  to  a 
design.  See  validation^ 
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Work  Breakdown  Structure.  An  enumeration  of  all  work  activities  in 
hierarchic  rehnements  of  detail  that  defines  work  to  be  done  into  short, 
manageable  tasks  with  quantifiable  inputs,  outputs,  schedules,  and 
assigned  responsibilities^  It  is  used  for  project  budgeting  of  time  and 
resources  down  to  the  iiKiividiial  task  level,  and  as  a basis  for  progress 
reporting  relative  to  meaningful  management  milestones. 

Worksheet  Forms.  Forms  defined,  programmed,  and  maintained  by  the  end 
user  in  an  end-user  faeilify  apiprpaeh  to  data  base  operations.  Worksheet 
forms  are  mappable  to  and  from  user  forms  and  perception  forms;  They 
are  used  for  extracting,  assembling,  and  viewing  of  data  by  the  end  user 
in  a "scratch  pad”  fashion,  as  a (perhaps)  temporaiy  device  pertinent  to 
that  user. 
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STANDARD  FLOWCHART  SYMBOLS 


Symbols  are  used  on  a flowchart  to  represent  the  functions  of  an 
information  processing  system.  These  functions  are  input/outpiit, 
processings  flow  path  and  direction,  and  annotation 

A basic  symbol  is  established  for  each  function  and  can  always  be  used  to 
represent  that  function.  Specialized  symbols  are  established  that  may  be 
us^  in  place  of  a basic  symbol  to  give  additional  information. 

The  symbols  given  in  this  appendix  derive  from  Arneriean  National 
Standard  Flowchart  Symbob  and  Their  Usage  in  Information  Processing, 
ANSI-X3.5-197G^  American  National  Standards  Institute,  Inc,,  New  York, 
Sept  1,  1970.  The  ANSI  usage,  in  some  cases,  has  been  refined  or  extended 
herein  to  conform  to  the  needs  of  structured  programming. 
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Table  Basic  flowchatt  symbols 


Symbol  and  dimensional  ratio 
(width;height) 

Meaning 

M 

1:2/3 

Input/Output  Symbol.  This  symbol  repre- 
sents an  I/O  medium  or  function,  such  as 
making  available  of  information  JV»: 
processing  (input),  or  the  recording  of 
processed  information  (output). 

1:2/3 

Process  Symbol.  This  symbol  represents 
any  kind  of  processing;  for  example,  the 
process  of  executing  a defined  operation  or 
group  of  operations  resulting  in  a change 
in  value^  form,  or  location  of  information. 

O 

1:2/3 

Decision  SyriAbnl.  This  symbol  represents  a 
specific  decision  or  switch  operation  that 
determines  which  of  a number  of  alternate 
paths  is  to  be  followed*  This  symbol  may 
not  be  striped. 

— 

1:2/3 

Comment  or  Annotation.  This  symbol  is 
used  to  enclose  descriptive  comments  or 
explanatory  notes  as  clarifiGation.  The 
broken  line  is  connected  to  any  symbol 
where  the  annotation  is  meaningful 

-! 

Sequence,  Control  Flow.  Sequential  pro- 
gram flow  is  indicated  by  single-line 
arrows  connecting  symbols.  Arrowheads 
are  necessary  to  show  direction.  Use  only 
one  arrowhead  per  flowline,  at  its  end 

J 

Information,  Data  Flow . Flow  of  informa- 
tion or  data  is  indicated  by  double-line 
arrows  connecting  symbols.  Arrowheads 
are  necessary  to  show  direction.  Tails  are 
optional,  but  recommended. 
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Table  B-1.  Basic  flowchart  symbols  (continuation) 


Symbol  and  dimensional  ratio 
(width:height) 

Meaning 

o 

1:1 

Loop  Collecting  Node.  The  small  open 
circle  shown  represents  the  iteiation  point 
in  a looping  operation. 

• 

1:1 

Decision  Collecting  Node.  The  small 
blackened  circle  shown  represents  the 
merging  of  alternative  floy/  paths  in  a 
program,  if  this  symbol  is  computer 
drawn,  it  may  be  desirable  not  to  have  the 
circle  completely  blackened,  but  filled,  say, 
with  an  asterisk,  as  shown. 

i 

i 1 

Begin  Concurrent  Mode,  or  Fork.  The 
symbol  shown  represents  the  beginning  of 
two  or  more  concurrent  (parallel  or 
interleaved)  processes. 

i i, 
i 

End  Concurrent  Mode,  or  Join.  The 
symbol  shown  marks  the  end  of  two  or 
more  concurrent  (parallel  or  interleaved) 
processes.  When  used  to  join  background 
and  interrupt  processes,  the  interrupt  logic 
is  disabled  on  resumption  of  sequential 
mode. 

C_) 

1:3/8 

Terminal  Symbol.  The  symbol  shown 
represents  the  entry  or  exit  point  of  a 
flowchart. 

^ 

1:3/8 

Interrupt  Symbol,  The  symbol  shown 
represents  the  enabling  (or  arming)  of  an 
interrupt  that  may  initiate  a concurrent 
(preemptive  interleaved)  process.  The 
process  reexecutes  each  time  the  event 
occurs  until  both  processes  reach  their 
join.  The  event  identifier  (name)  is  placed 
in  the  terminal  symbol. 
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Table  B-1.  Basic  flowebart  symbols  (continuation) 


Symbol  and  dimensional  ratio 
(widtb:height) 


Meaning 


Communication  Link  The  symbol  shown 
represents  a function  iii  which  information 
is  transmitted  by  a telecommunication 
link  Arrowheads  are  necessary  to  show 
direction.  Tails  are  optional  but  recom- 
mended. 
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Table  B^2.  Spedaltzed  I/O  flowchart  symbots 


Symbol  and  dimensional  ratio 
(width:height) 

Meaning 

/ 

1:1/2 

Punched  Card  The  symbol  shown  repre- 
sents an  I/O  operation  in  which  the 
medium  is  punch^  cards. 

f , 

6/4:2/3 

1 

Deck  or  File  of  Cards. 

LJ 

1:2/3 

r 

Online  Storage,  The  symbol  shown  repre- 
sents an  I/O  function  utilizing  any  type  of 
online  storage,  such  as  magnetiG  tape, 
drum,  or  disk. 

Q 

111 

Magnetic  Tape.  The  symbol  shown  repre- 
sents an  I/O  function  in  which  the 
medium  is  magnetie  tape. 

1:1/2 

■«Y 

Punched  Tape.  The  symbol  shown  repre- 
sents an  I/O  function  in  which  tne 
medium  is  paper  tape. 
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Table  B-2.  Speciaifzed  1/0  ^owchait  symbcils  (continuation) 


Symbol  and  dimensional  ratio 
(widththeight) 

Meaning 

LJ] 

sf4im 

Magnetic  Drum.  The  symbol  shown  repre- 
sents an  I/O  function  in  which  the 
medium  is  a magnetic  drum. 

2/3;S/4 

Magnetic  Disk.,  The  sjTilbo]  shown  repre- 
sents an  I/O  funetiori  in  which  the 
medium  is  a magnetic  disk. 

Core.  The  symbol  shown  represents  an  I/O 
function  in  which  the  medium  is  core 
storage. 

A-.m 

-J 

Document.  The  symbol  shown  represents 
an  T/O  function  in  which  the  medium  is  a 
document.  It  is  used  often  to  denote 
output  of  hard-copy  material  on  either  line 
printers  or  typewriter  terminals. 

{ 
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Table  B-2.  Specialized  I/O  fibwcbart  symbola  (continuation) 


Symbol  and  dimensional  ratio 
(widthiheight) 


Meaning 


1:1/2 


Manual  Input  The  symbol  shown  repre- 
sents an  input  funetion  in  which  informa- 
tion is  entered  manually  during  processings 
such  as  by  online  keyboards,  switches,  or 
push-buttotis. 


1:2/3 


Display,  The  symbol  shown  represents  an 
I/O  function  in  which  the  information  is 
displayed  for  human  use  at  the  time  of 
processing,  by  means  of  online  indicators, 
video  devices,  console  printer,  plotters, 
etc. 


Offline  Storage.  The  symbol  shown  repre- 
sents the  function  of  storing  information 
offline,  regardless  of  the  medium  on  which 
the  information  is  recorded. 


1:0,a^ 
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Table  B-3.  Speeialtzed  process  symbots 


Syntbol  and  dimenstohal  ratio 
(M^idth:height) 


Meaning 


1:2/3 


Internal  Procedure,  The  symbol  sliown 
represents  a named  procedure  (subprogram 
or  subroutine)  module  that  has  a more 
detailed  representation  elsewhere  in  the 
same  set  of  flowcharts.  Similar  horizontal 
striping  eonventions  apply  to  other  syin^ 
bpls^  as  well,  when  they  are  detailed  in  this 
way. 


1:2/3 


External  Procedure.  The  symbol  shown 
represents  a named  procedure  (subroutine) 
module  or  logical  unit  that  is  not  detailed 
in  this  same  set  of  flowcharts.  Similar 
vertical  striping  conventions  apply  to 
other  symbols^  as  well,  when  they  are 
detailed  elsewhere. 


1:2/3 


Preparation.  The  symbol  shown  represents 
the  preparation  of  a medium  for  process- 
ing, such  as  obtaining  core  storage,  declar- 
ing data  stniGtures,  or  initializing  varia- 
bles. 


1:4/9 


Indexed  Looping.  The  symbols  shown 
represent  loop  initialization,  predicate 
testing,  and  update  functions.  Testing 
always  follows  every  initiallzatiGn  and 


1:4/10 


Non-normal  Exit.  The  symbol  shown 
represents  the  exit  from  a process  due  to 
abnormal  or  paranormal  events. 


-J 
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Table  B^  Specialized  process  symbols  (continuation) 


Symbol  and  dimensional  raito 
(width:height) 


Meaning 


1:0:886 


Merge.  The  symbol  shown  represent  the 
combining  of  two  or  more  sets  of  items 
into  one  set 


Extract  The  symbol  shown  represents  the 
removal  of  one  or  more  specific  sets  of 
items  from  a single  set  of  items. 
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Table  Symbol  usage  in  flowcherttitg 


Illustration 


Usage 


Symbol  Shape.  The  actual  shapes  of  the 
symbols  used  should  conform  closely 
enough  to  those  shown  in  Tables  B-1,  B^2, 
and  B-3  to  preserve  the  characteristics  of 
the  symbol  The  curvature  of  the  lines  and 
the  angles  formed  by  the  lines  may  vaiy 
slightly  from  those  shown  in  this  standard, 
as  long  as  the  shapes  retain  their  unique- 
ness. 


Symbol  Size.  Flowchart  symbols  are  distin- 
guished oh  the  basis  of  shape,  proportion, 
and  size  in  relation  to  other  symbols, 
Proportion  of  a given  symbol  is  defined  by 
the  rectangle  in  which  that  symbol  can  be 
inscribed;  Dimension  and  relative  size  of 
the  rectangles  are  given  with  each  symbol 
by  a pair  of  numbers  (width:  height); 

The  size  of  each  symbol  may  vary,  but  the 
dimensional  ratio  of  each  symbol  shall  be 
maintained. 


Symbol  Orientation.  The  orientation  of 
each  symbol  on  a flowchart  should  be  the 
same  as  shown  in  the  tables  of  this 
appendix.  Flowline  symbols  (Either  control 
information,  or  data  flow)  may  be  drawn 
left-to-^righti  tpp^to-bottom,  right-to-left, 
or  bottom-to-top.  The  prihcipa:!  flow  of 
control  is  top-to-bottom.  The  principal 
flow  of  information  or  data  should  be 
depicted  as  left-to-right. 
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Tabte  B-4.  Symbol  usage  In  flowehartlhg^(eonUmietlon) 


Illustrafion 


Usage 


leftrto'flght 
top-to- 
bottom  text 


Flowchart  Text,  Descriptive  information 
within  each  symbol  shall  be  presented  so 
as  to  be  readable  from  left-to*right.  top-to- 
bottom,  regardless  of  the  direction  of  flow 


outside  the  box. 


Symbol  Identifleatipn.  The  identifying 
number  n assigned  to  a symbol  on  the 
current  flow  chart  shall  be  placed  above 
and  to  the  right  of  its  vertical  bisector. 
This  number,  concatenated  with  the  chart 
identifier  c,  forms  the  unique  symbol 
Dewey-decimal  identifier,  c.n.  If  the  sym- 
bol is  striped  and  if  there  is  no  explicit 
symbol  cross-reference,  then  the  number 
c.n  becomes  the  (implicit)  cross-referenc- 
ing chart  number  at  the  next  hierarchic 


level. 


Symbol  Cross-Reference.  The  identifying 
chart  number  or  other  erossrreferencing 
element  x shall  be  placed  above  the 
symbol  and  to  the  left  of  its  vertical 
bisecton  When  such  notation  appears,  it 
takes  precedence  over  the  symbol  identi- 
fier as  the  cross-referencing  scheme. 
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Table  B-4;  Symbol  usa^  In  ftowishaiting  (eontinuatkm) 


Illusttation 

Usage 

c*n 

(or  x> 

C ) 

Symbol  Striping.  A horizontal  line  is 
drawn  withiii,  completely  across,  and  near 
the  top  of  the  symbol,  and  a reference  to 
the  detailed  representation  is  placed  be- 
tween that  line  and  the  top  of  the  symbol. 
The  terminal  symbol  shall  be  used  as  the 
first  and  last  symbols  of  the  detailed 
representation^  The  entry  terminal  symbol 

W n 

contains  the  name  reference  that  also 

■ 

* 

appears  in  the  striped  symbol. 

Oh  Chart  t? 

1 

The  location  of  the  detailed  representation 
chart  is  contained  in  the  symbol  cross- 
reference  (af),  if  any;  otherwise  it  is 
referenced  by  the  concatenation  of  the 

On  Chart  c^n 
ior;r) 

chart  and  symbol  identifiers. 

In  either  case,  the  chart  number  is  placed 
above  and  to  the  left  of  the  vertical 
bisector  of  the  entiy  terminal  symbol. 

Connector  Identification.  A common 
identifier,  such  as  an  alphabetic  character, 
number,  or  mnemonic  label  (A)  is  placed 
within  the  connector  as  shown.  Additional 
cross-referencing  for  oflF-page  connectors 
shall  be  the  page  number,  p,  placed  above 
and  to  the  left  of  the  vertical  bisector  of 
the  symbol  (only  when  there  is  more  than 
one  such  page).  OflF-page  connectors  to  or 
from  flowcharts  of  other  modules  are  not 
permitted. 
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Tablo  B-4.  Symbol  usage  In  fjowcharUng  (contlnu^on) 


Illustration 


Usage 


Multiple  Control  Flow  Branches.  Multi^ 
pie  branchiBS  from  a ^mubol  are  restricted 
to  the  decision  symbol.  The  text  within  the 
symbol  shall  state  the  explicit  predicate  or 
event  that  causes  the  branch. 

For  each  conditioned  branch,  each  exiting 
ilovvline  is  to  be  labeled  by  text  that 
identifies  the  predicate  outeome.  Nor- 
mally, true  exits  to  the  left,  false  to  the 
right  in  binaiy  decisions;  multiple  branches 
exit  in  case-order  from  the  left  (if  there  is 
an  explicit  case  order). 


J ’ , 

^_....  .....  . , , ^ . _ ._  . ..^...  -■i.  ■ 


mi^  ^ 


APPENDIX  C 

SOFTWARE  REQUIREMENTS 
DOCUMENT  TOPICS 


This  appendix  contains  a detailed  outline  for  the  organization  of  software 
requirements  suitable  for  hierarehiG  refinement  of  detail.  The  first  sections 
contain  preliminaty  management  itifonnation  and  the  others  go  into  more 
technical  detail,  as  needed. 

Figure  C4  is  a top-level,  visual  table  of  contents  of  the  document 
Oiganizatibn,  The  suggested  topics  are  then  detailed  in  the  remainder  of 
this  appendix.  Each  of  the  topical  headings  is  follou^ed  by  a narrative 
description  for  the  material  to  be  inseiteA 

Much  of  this  material  may,  perhaps,  be  supplied  by  reference  or  by 
attachment.  Such  practice  is  to  be  encouraged,  inasmuch  as  the  SRD  is  not 
generally  a document  that  is  maintained  after  program  delivery. 


The  main  principle  behind  the  writing  of  the  SRD  is  that  it  gives 
management  only  what  it  needs  (the  SJR)  in  order  to  approve  the 
expenditure  of  funds  and  to  concur  with  the  schedule— at  least  for  the 
initial  (SDD)  study  phase  of  the  implementation— and  gives  implementation 
only  what  it  needs  (the  FRD)  in  order  to  respond  with  an  appropriate  SDD, 

See  Chapter  II  for  more  specific  and  detailed  rules  in  completing  the 
SRD. 
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SOFTWARE  REQUIREMENTS 
DOCUMENT 

Detailed  table  of  Contents 


FRONT  MATTER 


Tifle  Page.  Provide  a title  page  containing  (l)  document  number;  (2) 
SOFTWARE  REQUIREMENTS  DOCUMENT;  (3)  program,  project, 
subsystem,  and  system  titles;  (4)  release  date;  (5)  a signature-approval  block 
appropriate  for  the  management  authority  level  required;  and  (6)  releasing 
organization.  Signatures,  when  supplied,  signal  the  approval  to  proceed 
with  the  architectural  phase.  FRD  material  may  precede  SRD  approval,  or 
may  be  supplied  subsequent  to  approval 

Abstract.  Give  a brief  abstract  that  summarizes  the  program  requirements* 
inciuding  costs,  resources,  and  sch^ule. 

Change  Control  Information.  Provide  a brief  statement  that  identifies  the 
method  for  approval  and  for  arbitration  of  changes  in  the  SRD. 

Distribution  List  Provide  a distribiitioil  list  of  all  parties  who  are  to 
receive  copies  of  the  SRD^ 

Distribution  Information,  Provide  a statement  that  tells  how  additional 
copies  of  the  SRD  may  be  obtained. 

Table  of  Contents.  Provide  a detailed  table  of  contents  for  the  SRD,  which 
lists  section  number,  topic  title,  and  page  of  every  item  with  a heading, 
(This  is  probably  the  last  part  of  SRD  to  be  completed.) 


TEXT  OF  SOFTWARE  REQUIREMENTS  DOCUMENT 


1.  INTRODUCTION  AND  JUSTIFICATION 


1.1  Purpose  of  This  Requirement 

Provide  a brief  general  description  of  the  software  to  be  provided,  its 
purpose,  and  the  user  benefits  or  mission  characteristics  upon  which  the 
requirements  for  this  software  are  established. 
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Scope  of  Applicability 

SummaFize  the  level  and  type  of  material  that  appears  in  the  SRD* 
Identify  the  intended  readers,  State  the  criteria  that  govern  the  content, 
extent,  and  format  of  this  SRD.  If  pertinent,  proscribe  items  specifically  to 
be  outside  the  scope  of  this  application.  Reference  applicable  or  governing 
documents  as  appropriate. 

1^3  Applicable  Documents 

Identify  ail  documents  that  establish  technical  requirements,  set 
Gonstraiiits  and  policies,  or  regulate  the  procedures  to  be  used  in 
implementation. 

1.4  Establishment  of  Need 

1.4.1  History  and  Requireinent 

State  specific  user  needs,  mission  requirements,  market  potential,  or 
other  goals  to  be  satisfied  through  the  services  provided  by  the  software.  If 
pertinent,  trace  the  historical  development  of  the  application  to  be 
automated. 

1.4.2  Analysis  of  Current  Capability 

Describe  any  current  capability  or  in-progre?»  developments  that  respond 
wholly,  or  in  part,  to  the  needs  stated  in  1,4.1.  Identify  needs  for  which  no 
current  capability  exists,  and  give  limitations  oii  capabilities  that  do  exist. 
State  costs,  manpower,  and  other  performance  figures  for  providing  or 
maintaining  current  services,  if  these  are  pertinent  to  the  establishment  of 
the  need 

1.4.3  Analysis  of  Required  Capability 

Present  justification  for  the  development  of  software  to  fulfill  the 
requirements  above,  based  on  estimated  performance  gains  as  they  relate  to 
accomplishing  the  stated  goals  of  the  approving  organization. 

1.5  General  Description  of  the  Needed  Software 

Provide  an  introductory  description  of  the  software  to  be  developed^  and 
show  how  this  software  will  meet  the  needs  in  1.4.  Use  descriptions  as 
appropriate  to  characterize  the  program,  to  provide  tradeoff  studies,  to 
show  interrelations  between  the  program  and  its  application,  and  to  display 
its  major  operational  features. 

Identify  the  expected  program  life,  whether  the  program  will  be  a 
developmental,  interim,  or  operational  fulfillment  of  the  need,  and  estimate 
major  characteristics,  such  as  execution  mode  (real-time,  interactive,  batch), 
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computational  complexity  (number-cnmching  or  data  manipulative),  et(^ 
Use  graphic  aids  to  illustrate  these  features. 

U Feasibility  Studies 

Evaluate  the  proposed  software^  considering  timeliness,  technological 
and  economic  feasibility,  and  capabilityv  Identify  major  risks  that  will 
require  later  resolution. 

2.  MANAGEMENT  t^lF0RMA110^« 


2.1  Acqul^tlon  Method  or  Pisn 

2.1.1  Method  of  Acquisttiion 

State  the  method  to  be  used  to  develop  the  software,  such  as  in-house, 
outside  contract  or  some  mixture  of  the  two,  e.g.,  in-house  definition  and 
design  with  outside  coding  and  checkout.  If  done  by  outside  coiitract,  state 
the  proGurement  cycle  lead  times  and  other  constraints  pertinent  to  outside 
contract  or  purchase  of  software  relative  to  this  development  activity. 

2.1.2  Responsible  Croup  and  Staff 

Identify  the  in-house  organization  responsible  for  the  software 
development  and  identify  cognizant  individuals  as  appropriate. 

2.2  Funding  and  Manpower 

2.2.1  Total  Project  Estimates 

State  the  aiiiourit  and  source  of  funding  to  be  allocated  to  manpower, 
procurements,  and  services,  for  both  in-hpuse  and  outside-contract  parts  of 
the  development  State  methods  used  to  estimate  these,  aiid  stPte  the 
probable  accuracy  in  the  estimates. 

2.2.2  Architectural  Phase  Estimate 

Detail  the  manpower  and  funding  required  for  the  architectural  study 
phase  of  development.  Place  limits  on  the  expenditures  during  this  phase 
that  are  not  to  be  exceeded. 


2.3  Milestone  and  Review  Schedule 

Provide  a milestone  schedule  showing  estimated  major  tasks,  priorify 
phasing,  review  milestones,  and  software  deliveries.  State  methods  used  to 
estimate  schedule  events.  If  PERT  is  used,  state  critical-path  parameters. 
Set  milestone  and  probable  accuracy  by  requirements  keyed  to  mission 
objectives.  Show  the  architectural  phase  in  detail^  and  state  not-to-be- 
exceeded  limits  on  the  completion  of  this  phase. 
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2.4  Software  Deliverable 

Provide  a checklist  of  specific  items  required  for  delivery*  If  deliveiy  is 
phased  or  prioritized,  then  state  any  requirements  that  define  ddiverable 
items  relative  to  phases  or  priorities*  ■ 

3.  ENVIRONMENT  AND  INTERFACE  REOUIREMENTS 

Introduce  the  general  environment  within  which  the  program  is  to 
operate,  in  which  are  identified  the  users,  operators,  and  maintenance 
personnel,  the  envisioned  or  required  system,  and  the  interfaces  with  each 
of  these.  If  pertinent,  describe  the  working  environment  of  personnel 

Identify  whether  the  required  environment  is  curreritly  existing,  or 
whether  portions  will  have  to  be  purchased,  teased,  or  otherwise  created, 
either  on  a dedicated  or  time-shared  basis. 


Illiistrate  the  environmental  requirements  graphically  as 'well  as  verbally. 
Show  the  flow  of  data  or  paperwork  from  the  users  through  the 
application; 

Use  hierarchic  levels  of  detail  provided  below  as  appropriate  to 
characterize  the  environment  (required  or  existing),  to  provide  tradeoff 
analyses,  to  show  interrelations  between  environmental  attributes^  and  to 
display  the  major  environmental  features* 

3.1  User  Environment  Requirements 

Identify  and  describe  assumed  or  required  user  interfaces,  such  as  who 
the  users  are,  where  they  are  located^  what  their  sources  of  data  are,  how 
they  will  generate  and  submit  data  to  the  program  or  request  rtiiis,  how 
they  will  make  use  of  the  output,  other  manual  tasks,  etc.  Defer  user 
procedures,  formats,  units,  etc.,  until  Section  5.2  (User  Requirements), 

3.2  Operational  Environment  Requirements 

Identify  and  describe  assumed  or  required  operator  interfaces,  such  as 
control  devices,  input  devices,  operator  procedures,  data  generation 
methods,  mearis  for  delivery  of  output  to  users,  manual  tasks^  etc*  Identify 
those  requirements  that  are  unique  to  this  program  and  not  covered  by  an 
^>verall  system  requirement  or  governing  document.  Defer  operational 
procedures,  fonnats,  units,  etc.,  until  Section  5.3  (Operational  Rsequire- 
mehts).  State  any  qperatibhal  requirements  for  security,  privacy,  and 
protection  of  program  resources, 

3.3  System/ Subsystem  Environment  and  Interface  Requirements 

Provide  a narrative  overview  of  the  total  system  in  which  the  program  is 
required  or  will  be  assumed  to  operate.  Include  graphic  material  as 
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appropriate,  such  as  a block  diagram  of  the  pertinent  system  hardware  and 
software. 

3>3*1  Hardware  Characteristies  and  Constraihtis 
Describe  the  hardware  resources  that  may  be  ^sumed  or  are  required  as 


3.3.2  Software  Characteristics  and  Constraints 

Describe  the  software  envirorunent  in  which  the  program  is  to  operate^ 
and  identify  required  software  resources  and  other  constraints  on  the 
development,  such  as  required  interfaces  with  existing  user  programs,  data 
bases^  compilers,  diagnostics,  system  software,  etc.  Identify  known 
documents  and  manuals  required  for  program  development.  Defer  details 
of  units,  formats,  media,  etc.,  until  Section  5.4. 


3.4  Development  Support  interlaces  and  Requiremente 

Identify  and  describe  any  special  interfaces  required  during  development, 
as  well  as  requirements  for  any  supporting  facilities  or  resources,  such  as 
staffing^  services,  special  software  or  hardware,  computer  timej  manuals  or 
documents,  logisticsy  etc.,  which  are  applicable  to  the  development  aetivify 
but  not  covered  by  3»1,  3.2,  or  3.3, 


3^  Training  Requirements 

Describe  any  training  requirements  that  may  impact  program  develop- 
ment,  conditions  for  delivery,  or  later  program  maintenance  and  operation. 


4.  POUCIES  AND  CONSTRAINTS 

4.1  Standard  Practices,  Policies,  and  Procedures 

4.14  Established  Develppment  Practices,  Policies,  and  Procedures 

Identify  any  existing  appropriate  practices,  policies,  and  procedures  or 
controlling  documents  that  wiU  be  applicable  to,  and  required  of,  the 
development  of  the  program. 

44.2  Exceptions  to  Established  Fraciiccs,  Policies,  and  Procedures 

Identify  extensions,  modifications,  additions,  or  other  exceptions  to 
establish^  policies  in  4.1.1 , above.  Include  a description  of  any  special 
practices,  policies,  or  procedures  applicable  to,  and  required  ofy  the 
development  of  the  program. 
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4.2  Approach  RequIiBmehta  and  Gonstraints 

4^2.  i Development  Philosophy 

Include  a brief  desGription  of  the  philosophy,  principles,  or  disGiplines 
required  in  developing  the  prograni. 

4.2.2  Development  Gonstraints 

Identify  any  constraints  to  be  placed  on  the  development  approach,  such 
as  design  programrniitg  language,  maximum  core  size,  required 

speed  of  execution,  use  of  available  subroutines,  special  interface  design 
procedures,  etc. 


4.3  Pridrities  and  Phasing 

Define  priorities  of  requirements  and  give  guidelines  governing  how 
resources  may  be  allocated  and  conflicts  resolved  in  order  to  accommodate 
these  priorities.  Define  phases  of  partial  capabiUty  during  development  or 
to  be  delivered  if  the  entire  program  is  not  to  be  developed  or  delivered  all 
at  once. 

4.4  PerformaniDe  Requirements 

4.4.1  Reviews  and  Approvals 

Identify  all  required  reviews,  the  content  of  such  reviews,  the  makeup  of 
the  review  board,  the  convening  authority,  and  the  action  of  the  board; 
state  the  degree  to  which  board  approval,  or  other  authority,  is  required  in 
order  to  continue  development, 

4^4.2  Change  Procedures 

Describe  procedures  to  be  followed  by  the  developers,  users,  or  others  in 
soliciting  or  effecting  changes  to  the  SRD  if  not  already  covered  by  Section 
4,1,1. 

4.4.3  Performance  Measures 

State  criteria,  in  oider  of  importance  or  by  weight,  by  which  the 
performance  of  the  developers  will  be  judged  satisfactory,  sucH  as  (l) 
effective  control  of  cost,  performance,  and  schedules;  (2)  timeliness  in 
responding  to  new  guidelines  or  events;  (3)  achievement  of  techniGal  goals; 
(4)  sensitivity  to  environment,  including  rules  and  policies;  (5)  Gonformance 
to  standards  requirements;  (O)  maintenance  of  adequate  progress  visibility; 
etc, 

4.5  Documentation  and  Reporting  Requirements 

Identify  the  types  of  reports  and  documentation  to  be  produced,  and 
establish  specifications  governing  the  level  of  detail,  format,  medium, 
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quality,  and  mode  of  ddiveiy.  Include  requirements  for  interim  progress 
and  QA  reports,  as  well  as  planning,  design,  coding,  testing,  and 
maintenance  documentation,  as  appropriate. 

5.  FUNCTIONAL  REQUIREMENTS 

(This  section  documents  the  overall  functional  characteristics  required  of 
the  program,  to  a level  of  detail  sufficient  to  allow  the  architectural  design 
to  proceed  mth  adequate  assurance  to  management  that  what  was 
approved  will  actually  be  done. ) 

Develop  the  program  I/O  and  processing  requirements  in  hierarchic 
levels  of  detail.  Use  graphic  aids,  such  as  information  flow  graphs,  block 
diagrams,  or  procedural  flow  graphs,  and  narrate  the  requirements 
concisely,  but  clearly  and  adequately 

5.1  Functional  Overview 

Describe  the  top-level  requirement  details  of  the  operational  software. 
Typical  coverage  at  this  point  might  address  the  structure,  data  flow, 
functional  interfaces,  major  operating  modes,  utility  factors,  security/ 
protection,  planned  later  modifications  or  extensions,  etc.  If  graphics  are 
used,  support  these  with  narrative  explanations.  Although  such  require- 
ments may  be  general  in  nature,  they  should,  nevertheless,  be  described  in 
complete  sentences  (e.g,,  “Decompose  the  telenietry  stream  into  frames"  is 
preferred  over  “process  telenietiy”). 

5.2  User  Requirements 

State  any  specific  procedural,  format,  or  information  content  require- 
ments on  the  software  (program  plus  documentation)  that  relate  to  the 
fimctional  behavior  as  viewed  by  the  iiser(s). 

5.3  Operational  R^ulrements 

State  any  specific  procedural,  format,  control,  or  information  content 
requirements  on  the  software  (program  plus  documentation)  that  relate  to 
the  functional  behavior  as  viewed  by  the  pperator(s). 

5«4  Input,  Processing,  and  Output  Requirements 

Present  a hierarchic  development  of  input,  processing,  and  output 
requirements  (using  HIPO  or  other  diagrams  if  needed).  At  each  level  in  the 
hierarchy,  present  the  following  information  (either  structured  or  integrated 
narrative)  for  each  functional  requirement  being  described: 

Input  Present  a general  description  of  the  input  parameters,  special 
data,  necessary  formats,  initial  conditions,  and  special  controls  that 
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apply  to  the  requirement  being  defined;  Include,  where  pertinent, 
jegulrements  for  units  of  measure^  limits  and/or  ranges  of 
acceptability,  accuracy/precision,  frequency  of  arrival,  etc. 

Processing,  Describe  the  processing  required  on  the  input  data, 
including  requirements  for  transformations,  sequencing,  logical 
concepts,  timing,  reductions,  internal  program  checks,  accuracies, 
tolerances,  data  manipulations,  throughput  rate,  and  control  options, 
as  appropriate,  in  a logical  presentation  sequence  Include  equations 
to  be  solved  if  necessaiy*  If  the  program  requires  a particular 
sequence  of  operations  and/or  a significant  decision  process,  include 
their  descriptions  (cig*,  as  flow  chart  and/or  decision  table,  plus 
narrative). 

Output  Describe  output  requirements  on  display,  storage,  transmis^ 
sion,  control,  or  other  data,  including  units  of  measure,  accuracy/ 
precision,  frequency  of  output,  medi^  etc.,  as  appropriate. 

Ihteifaces,  Describe,  as  needed,  any  additional  detailed  functional 
relationships  of  the  interfaces  of  the  program  with  other  programs, 
the  system,  or  other  processing  requirements  herein  described.  If  a 
system/subsystem  interface  specification  has  been  produced,  it  may 
he  referenced  as  the  controlling  document. 

Diagnostics.  Specify  the  requirements  for  any  diagnostics,  error 
detection,  and  recovery  that  must  be  designed  into  the  function  being 
described,  (in  general,  other  program  diagnostics  will  also  be 
designed  into  the  program  during  implementation;  however,  those 
diagnostic  features  shall  be  required  to  include  any  diagnostics 
prescribed  in  this  section.) 

5.5  Data  Base  Requirements 

Describe  in  general  and  quantitative  terms  the  requirements  for  the  data 
base(s)  to  be  produced  or  used  by  the  program.  Include  parameter 
requirements  that  affect  the  overall  design  of  the  program  (or  system  of 
programs  in  which  this  program  is  a part),  emphasizing  data  characteristics 
and  data  relationships,  and  including  ranges,  units  of  measure,  accuracy/ 
precision,  etc.,  where  applicable.  Identify  constraints  that  could  prove 
critical  during  design  and  implementation.  Describe,  as  appropriate, 
requirements  for  data  collection,  conversion,  and  distribution. 

& ACCEPTANCE  AND  EVALUATION  CRITERIA 
6.1  Competing  Characteristics 

Include  a list  of  factors  or  features  that  compete  for  development 
resources  and  order  these  linearly,  or  in  a matrix,  according  to  their 
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importance  in  meeting  the  progr^  teehnie^il  requirements,  such  as  (l) 
program  size,  (2)  execution  speed,  (3)  cost  to  develop,  (4)  time  to  develop, 
fS)  vulnerability  to  operator  or  input  error,  (6)  maintainability^  (7)  growth 
potential,  (8)  documentation  readability,  (9)  portability  or  machine 
independence,  and  (lO)  cost  to  operate.  Identify  any  known  special 
circumstances  that  may  tend  to  negate  or  reorder  these  priorities.  State  how 
major  conflicts  in  pHorittes  are  to  be  resolved. 

6.2  Acceptance  Requirements  and  Criterie 

6.2.1  Demonstration  Gonflguiation 

State  requirements  relating  to  the  location,  coniiguratibn,  conduct  and 
review  of  acceptance  tests. 

6.2;2  Criteria  for  Acceptance 

Provide  a list  of  criteria  or  conditions  defining  when  the  software 
development  task  is  complete,  and,  therefore,  when  the  format  transfer  of 
responsibility  to  operational  and  user  organizations  can  take  place. 

6.2.3  Testing  Requirements  and  Criteria 

State  specific  requirements  on  the  form  and  extent  of  tests  that 
demonstrate  the  acceptability  of  the  software,  or  reference  such  documents 
as  contain  this  ihfonnation.  Include,  as  appropriate,  requiremetits  for 
demonstration  of  control  and  data  I/O  interfaces,  logical  conditions, 
processing,  and  diagnostic  functions.  Specify  performance  criteria  by  which 
test  results  will  be  judged  to  have  demonstrated  acceptable  behavior. 

6.2.4  Test  Result  Documentation 

Reference  applicable  documents  that  specify  the  format,  content,  quality, 
and  level  of  detail  required  in  assembling  the  test  data  into  a coherent 
record  of  test  results;  otherwise,  provide  these  requirements  in  this  section. 

6.3  Quality  Assumnce  Requirements 

Reference  applicable  documents  that  specify,  or  identify  in  this  section, 
the  QA  organization  and  its  level  of  involvement  in  the  software 
deliverables.  Include,  as  appropriate,  requirements  for  inspections  of 
workmanship,  configuration  control,  material  Gusiodianship,  quality 
control,  software  (documentation)  audits,  etc>  Provide  criteria  that  specify 
the  extent  to  which  QA  reports  concerning  the  adequacy  of  the  delivered 
software  are  a binding  condition  for  delivery. 

7.  APPENDICES 

Appendices  may  include,  but  are  not  limited  to,  explanatory  material  and 
requirements  of  an  auxiliary  nature,  inserted  directly  or  bound  separately 
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for  convenience.  *Che  following  suggested  topics  are  ^icaL  Appendices 
may  be  designated  as  “Appendix  A,”  etc.*  if  desired^  rather  than  by  the 
Dewey-Decimal  system  given  here. 

7.1  Glossary 

Provide  an  alphabetical  listing  of  terms*  symbols*  mnemonics,  acronyms* 
etc.,  used  in  the  body  of  the  SRD  having  a special*  not  widely  known  use. 

7:2  References 

Provide  a list  of  all  source  docpiments,  standards,  procedures*  and 
references  cited  in  the  SRD  body  {or  elsewhere  in  the  appendices).  Give  a 
short  description  of  the  information  referred  to  in  each*  if  not  evident  from 
the  title. 

7.3  Analyses 

Provide  analyses  of  program  requirements  as  appropriate  to  support  or 
clarify  functional  requirements  stated  elsewhere  in  the  SRD. 

7.4  Formats  and  Auxiliary  tables 

If  detailed  format  requirements  have  been  established  by  this  SRD,  and  if 
these  are  more  appropriately  accommodated  in  an  appendix  raither  than  in 
the  SRD  proper,  then  insert  such  information  in  Riis  section,  Similarly, 
insert  any  requirements  appended  in  tabular  form  in  this  section  (or* 
perhaps,  as  separate  appendices). 

7.5  Typical  Run  Examples 

In  cases  where  illustrations  of  requirements  take  the  form  of  examples*  to 
which  the  executing  program  is  to  conform*  and  when  these  requirements 
are  better  appended  than  inserted  in-line  in  the  SRD  proper,  then  insert 
such  examples  in  this  section. 
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This  appendix  contains  a detailed  outline  for  the  assemblage  of  program 
design  definitions  into  a document  for  management  visibility  and  approval. 
On  completion,  the  document  defines  the  program  functional  and  internal 
architecture,  costs,  schediilfe,  development  plan  and  related  matters  to  that 
extent  which  permits  a competent  technical  and  management  review  of  the 
software  to  be  delivered. 

Figure  D-1  is  a top-level  view  of  the  document  organization;  greater 
hierarchic  detail  is  provided  in  the  detailed  outline  that  follows,  The 
detailed  outline  also  contains,  along  with  each  topical  heading,  a 
description  of  the  material  to  be  inserted  at  that  point 

Much  of  the  material  cited  herein  for  inclusion  can  perhaps  he  satisfied 
by  references  to  suitable  documentation  elsewhere,  or  by  attachment  to  the 
SDD.  Such  practice  should  be  encouraged  whenever  the  reference 
documents  are  stable,  or  are  under  some  acceptable  change  control 
mechanism,  or  else  when  any  instabilities  or  changes  in  those  references  are 
not  apt  to  affect  the  management  information  given  in  the  SDD,  Technical 
details  at  this  point  are  primarily  important  only  to  the  extent  that  they 
impact  management  decisions. 

The  principal  guideline  for  the  SDD  content  is  that  it  includes  only  that 
amount  of  technical  detail  needed  early  in  the  development,  which  defines 
management  resource  requirements,  the  program  general  architecture, 
refined  costs,  and  refined  schedules.  The  SDD  is  not  generally  maintained 
after  program  deliveiy. 

See  Chapter  11  for  more  specific  and  detailed  rules  for  completion  of  the 
SDD, 
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SOFTWARE  DEHNinON  DOCUMENT 
Detailed  Table  of  Contents 


FRONT  MATTER 

Title  Page,  Provide  a title  page  containing  (l)  document  number;  (2) 
SOFTWARE  DEFINITION  DOCUMENT;  (3)  title  of  the  program, 
subsystem,  and  system;  (4)  the  publication  date;  (S)  signature  approval 
block  appropriate  for  the  management  authority  level  required;  and  (6) 
releasing  organization.  Approval  signatures  will  be  appli^  to  continue 
detailed  software  development. 

Abstract.  Give  a brief  abstract  that  summarizes  the  material  contained  in 
the  SDD. 

Change  Control  Information.  Provide  a brief  statement  that  specifies  the 
level  of  change  control  to  be  exercised  on  the  SDD  during  the  time  of 
preparation.  On  completion,  revise  this  statement  to  reflect  the  proper 
post-signature  change  control  policy  and  procedure. 

Distribution  Information*  Provide  a distribution  list  of  all  parties  with 
need-to-know  status  of  the  SDD  who  are  to  receive  copies.  Provide  a 
statement  that  tells  how  additional  copies  may  be  obtained 

Table  of  Contents.  Provide  a detailed  table  of  contents  for  the  completed 
SDD,  which  lists  section  number,  title,  and  page  of  eveiy  item  with  a 
heat -ng.  ^is  table  is  probably  the  last  item  supplied  to  the  SDD  prior  to 
completion. 


TEXT  OF  DESIGN  DEFINITION 

1.  INTRODUCTION 

1,1  Purpose  of  the  FN^gram 

Provide  a brief  statement  of  the  purpose  of  the  program  and  of  this  SDD. 
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1.2  Scope  of  this  Document 

Provide  a brief  statement  that  defines  the  scope  of  material  contained  in 
this  SDD,  including  a brief  statement  that  scopes  each  major  section  of  the 
document,  if  necessaiy. 

1.3  Applicable  Documents 

Identify  all  controlling  documents  to  which  this  SDD  responds. 

1.4  General  Description  Of  the  Operational  Environment 

Provide  an  orientation  for  the  reader  that  shows  the  software  imbedded 
in  its  operational  environment  (both  hardware  and  software).  A dataflow 
block  diagram  with  explanatory  narrative  is  useful  here.  Identify  the 
general  mode  of  operation  of  the  program,  such  as  ‘"stand-alone,  interrupt- 
driven,  real-time  program  on  dedicated  XXXX  minicomputer  operating 
under  OSOSOS  operating  system  with  a 64K-word  core  and  two  lOM-byte 
disks/*  Identify  any  other  general  system  constraints  imposed  by 
requirements  or  are  otherwise  critical  to  the  design.  Defer  details,  however, 
to  Section  3.  The  emphasis  at  this  point  is  on  communicating  an 
understanding  among  readers  concerning  the  overall  operational  interfaces, 
and  not  on  the  detailed  computer  and  peripheral  interfacing  aspects. 

IS  General  Description  of  the  Program  Architecture 

Provide  an  overview  of  tl^e  program  function,  response  to  requirements, 
nature  of  the  problem  and  type  of  data  input,  processed,  and  transmitted, 
etc.  Identify  the  type  of  program,  such  as:  (l)  real-time,  interactive,  or 
batch;  (2)  computational  or  data  manipulation;  and  (3)  developmental  or 
operational.  ' vr  descriptions  contained  in  the  SRD  may  be  referenced  and 
may  provide  a portion  of  the  level  of  understanding  needed  at  this 
point.  However,  any  new  general  information  not  in  the  SRD  should  be 
given.  A data-flow  or  diagram,  tier  chart,  or  other  form  of  high-level 
program  block  diagram  which  displays  the  program  architecture  may  be 
useful  to  illustrate  the  program  and  its  major  mode  of  operation.  Defer 
details  to  Section  5. 

1.6  Assessment  of  Feasibility 

Summarize  the  results  of  program  analyses,  cost  and  schedule 
considerationsj  availabilify  of  personnel,  and  other  factors  (such  as,  perhaps, 
salability,  profit,  organizational  goals,  etc.),  which  impact  the  development 
of  this  piece  of  software.  If  alternate  plans  are  available,  being  developed 
under  similar  criteria  or  for  special  contingencies^  then  identify  these 
alternatives  and  their  viability.  Discuss  problem  areas  and  areas  of  concern 
resulting  from  architectural  study. 
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2.  MANAGEMENT  GUIDEUNES 

This  section  is  a suniF!ary  of  the  project  resources,  work  schedule,  and 
plans  for  implementing  the  requirements  given  in  the  SRD.  The  detail 
includes  estiimates  for  costs  and  schedule  based  on  an  analysis  of  the 
individual  functions  to  be  provided,  the  estimated  time  to  design,  code, 
test,  and  document  each  such  function  and  configuration  to  be  deliver^, 
and  the  resources  available  to  perform  the  task.  A set  of  characteristics  that 
compete  for  machine  and  management  resources  is  prioritized  as  a guide 
toward  implementation  (Section  4.3),  and  it  is  upon  this  ordered  priority 
that  the  given  resource  estimates  are  valid.  The  schedule  and  work  plan 
display  how  the  management  resources  are  organized  to  accommodate 
these  priorities,  so  that,  in  the  unlikely  events  of  schedule  or  cost  overruns, 
the  highest  priority  items  at  least  will  have  been  provided 

2.1  Team  and  Work  Breakdown  Structure 

Identify  the  manpower  allocations  for  development  and  show  a 
breakdown  of  work  into  tasks.  Identify  personnel  assigned  to  tasks  by  name 
when  possible.  Identify  project  management,  supervision,  design,  coding, 
documentation,  testing,  QA,  review,  secretariat,  and  liaison  functions.  Based 
on  work  identified  in  each  of  the  task  areas,  available  personnel,  planned 
work  phasing,  and  the  project  team  structure,  provide  a manpower  profile 
for  the  software  production,  testing,  documentation,  and  delivery.  Include 
favorable  and  adverse  tolerance  figures  for  these  estimates  and  state  the 
basis  for  such  estimates.  In  particular,  state  the  assumed  individual 
productivity  (say,  as  lines  of  code  per  day  per  individual)  used  in  estimating 
costs  and  the  schedule  of  the  following  sections. 

Provide  an  analysis  based  on  the  Work  Breakdown  Structure  of 
manpower  loading,  flow  of  expenditures  for  computer  facilities  and 
services,  and  other  factors  that  influence  the  level  of  support  required  for 
the  software  development.  Provide  a definition  of  the  work  priorities  and 
indicate  how  the  design  and  implementation  process  accommodates  the 
priority  ranking. 

2.2  Cost  and  Manpower 

Give  the  projected  or  allocated  dollar  and  manpower  costs  to  complete 
the  program  through  documentation,  testing,  and  delivery. 

2.3  Milestone  and  Review  Schedule 

Present  a more  detailed,  sharp-milestone  refinement  of  the  schedule 
given  in  the  SRD,  and  point  out  any  major  difiFereiices,  problems, 
reservations,  or  qualifications. 


268  Appendix  D 


2.4  Installation  Plan  Summary 

Summarize  the  plans  for  implementing  the  software  and  integrating  it 
into  its  system  and  operational  environments.  Describe  any  negotiations  or 
agreements  necessary  to  end  the  development  activity  and  deliver  the 
program  into  operation. 

2.5  Resouroea  and  Support 

State  the  planned  resources  and  also  support  other  than  dollars  and 
manpower  that  will  be  required  to  develop  the  software^  insofar  as  these 
are  drivers  for  cost,  schedule,  manpower,  or  program:  architecture.  Include 
avaiiaibility  of  critical  facilities,  subcontract  negotiations,  etc.,  as 
appropriate.  Identify  deficiencies,  either  incompletely  resolved  or 
undefined,  as  liens  only  if  these  are  currently  a problem  or  if  they  typically 
would  not  be  resolved  later,  prior  to  projected  needs  during  actual  work 
phasing. 

3.  ENVIRONMENT  AND  INTERFACES 

This  section  expands  upon  the  overview  presented  as  Section  1.3.  Its 
function  is  to  define  the  scope  of  the  task,  not  to  define  the  system, 
environment,  and  interfaces  in  detail. 

3.1  User  Environment 

Describe  che  user  interfaces  with  the  program  and  the  functions  that  user 
interactions  invoke  within  the  program.  Use  references  to  user  manuals,  the 
SRD,  and  other  such  materials  that  describe  those  aspects.  Include  only  that 
information  which  impacts  either  the  program  architecture  or  the 
management  resources  needed  for  implementation.  Leave  other  details  for 
the  SSD  and  the  User  s Manuaj(s). 

3.2  Operational  Environment 

3.2.1  Operational  and  Operator  Interfaces 

Describe  operational  and  operator  interfaces  with  the  software  being 
developed  to  that  level  of  detail  at  which  impacts  to  management  resources 
and  major  technical  decisions  are  typically  felt.  Use  references  to  the  SRD, 
operator  manual(s),  technical  manuals,  liaison  personnel,  etc.,  to  obtain  the 
level  of  detail  and  information  deemed  proper. 

3.2.2  Operations/Maintenance  Flans 

Describe  the  measures  to  be  used  or  developed  for  maintaining  or 
operating  the  program  prior  to  delivery,  and  indicate  the  suitability  of  these 
measures  as  preliminaiy  operational  methods  after  delivery.  Identify  the 
post-delivery  operations/maintenance  responsibility. 
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3.3  System/Suiisystent  Interfaces 

Outline  both  the  hardware  iuid  software  aspects  of  the  system  and/or 
subsystem  that  are  needed  to  define  the  program  architecture  or  else  are 
projected  to  influence  the  program  architecture  signifieantly  if  not 
identified  and  resolved  early.  Indicate  maximum  available  core,  segmenta- 
tion constraints,  system-imposed  timing  constraints,  the  use  of  existing  or 
standard  subroutines,  etc,,  as  appropriate^  Reference  existing  hardware  and 
software  technical  manuals,  system  technical  requirements  documents,  etc,, 
if  appropriate. 

3.4  Program  Development  Environment 

Describe  and  discuss  any  aspects  of  the  environment  in  which  the 
software  is  being  written,  designed,  coded,  tested,  etc.,  that  will  contribute 
to  adverse  or  favorable  deviations  from  the  plan  of  this  SDD,  should 
certain  identified  contingencies  be  or  not  be  realized.  For  large  programs 
that  require  a work  breakdown  structure,  describe  the  functional  interfaces 
which  are  to  be  maintained  during  program  development.  This  section  is 
generally  only  warranted  when  problems  are  projected  to  arir:3  due  to  the 
development  environment. 

4.  DESIGN  GUIDELINES  AND  CONSTRAINTS 

This  section  consists  of  material  that  defines  and  constrains  the 
development  disciplines  and  conventions  used  by  the  project. 

4.1  Standards  and  Conventions 

Define  in  this  section  those  special  standards  and  conventions  that  apply 
to  this  SDD,  Additionally,  identify  or  describe  any  special  standards  or 
conventions  necessary  for  developing  the  software,  but  only  if  these  are  a 
major  consideration  in  establishing  the  costs,  manpower,  schedule,  or 
program  architecture.  Established  standards  and  conventions  may  be  cited 
by  reference. 

4.2  Approach  Guidolinea 

Define  any  special  methodology  to  be  used  to  develop,  code,  or  test  the 
software,  and  state  any  special  approach  or  design  philosophy  toward 
solving  the  software  design  problems,  insofar  as  these  are  instrumental  in 
determining  costs,  manpower,  schedule,  or  program  architecture.  Standard 
methodologies  or  approaches  will  have  been  covered  by  4.1,  above. 

4.3  Priorities  and  Competing  Gharacteri^lcs 

List  the  significant  technical  and  management  factors  that  compete  for 
costs,  schedule,  and  program  and  documentation  quality,  Prioritize  these  so 
as  to  fulfill  the  design  philosophy,  documentation  plans,  and  SRD 
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requirements.  Include  such  considerations  as  progrmn  size,  execution  speed, 
vulnerability  to  operator  ermr^  maintainability,  growth  capability  or 
extension,  portability  of  design,  readability  of  documentation,  level  of 
dpcumentatibn^  vulnerability  to  system  errors,  etc,,  but  only  include  such 
factors  if  they  are  deemed  to  impact  costs  and  scheduics, 

AA  Documentation  Guidellnea  and  Constraints 

Identify  the  documents  to  be  produced,  the  purpose,  type,  and  level  of 
quality  of  each,  the  intended  reatler,  the  projected  life  cycle,  and  the 
allocated  resources  that  have  bpen  planned  for  each.  Identify  any 
documentation  factors  that  need  resolution  and  that  will  significantly 
impact  management  resources.  Include,  as  appropriate,  project  logs, 
reports,  notebooks,  etc.,  as  well  as  deliverables.  Name  Individuals 
responsible  for  each. 

4.5  Design  Control 

State  summarily  the  level  of  design  control  exercised  within  the  project, 
and  state  the  impact  of  this  philosophy  on  technical  and  management 
resources.  Describe  the  methods  and  disciplines  to  be  imposed  or 
developed  to  assure  configuration  control  and  management  of  the  evolving 
software. 

5,  PROGRAM  ARCHITECTURE 

This  section  reveals  the  top-level  program  iunetional  and  modular 
hierarchy  of  algorithmic  design  structure.  Its  function  in  the  SDD  is  to 
provide  credibility  for  cost/schedule/manpower  estimates  and  allocations, 
and  a basis  for  reviewing  the  architectural  derign  that  will  be  used  in  the 
SSD. 

This  section  should  demonstrate  that  the  program  architecture  satisfies 
the  following  criteria:  (l)  adequacy  to  fulfill  ihe  program  requirements,  (2) 
adequacy  for  continuing  the  design,  (3)  adequacy  for  coding  the  design  from 
the  top  down  oil  a module  basis,  (4)  adherence  to  program  development 
standards,  and  (S)  adequacy  for  u.se  of  the  SSD  as  the  principal  sustaining 
document  after  software  delivery. 

5.1  Architectural  Overview 

Describe  and  discuss,  in  summary  form,  die  overall  program  organiza- 
tion^ both  functionally  (external  characteristics)  and  algorithmically 
(internal  characteristics)*  Only  the  major  functions,  algorithms,  data 
structures,  and  inputs/outputs  that  define  the  program  architecture  need  to 
be  addressed  at  this  point.  Such  deseript ions  may  take  the  form  of  modiiiar 
data  flow  descriptions  within  the  system  or  subsystem,  or  within  the 
program;  they  may  take  the  form  of  a high-level  tier-chart  with  explanatory 
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n^rative;  they  may  take  the  form  of  stnictured-contrbl  flowcharts  and  data^ 
strtic!7ire  diagrams  (always  with  explanatory  narrative)  to  show  the  program 
algorithmic  composition;  and,  for  complex  Gontrol-logie  situations,  they 
may  take  the  form  of  modular  decision  tables.  Indicate,  based  on  the 
architectural  study,  the  approximate  core  occupancy,  segmentation 
requirements,  timing  constraints,  etc. 

5.2  Modbs  of  Operation 

Identify  the  major  operating  modes  (or  ways  of  operating  the  program,  as 
selected  by  control  data  inputs)  and  the  diflferent  software  configurations  (if 
more  than  one  exists).  Discuss  summarily  the  behavior  of  the  program  in 
each  mode  or  configuration,  the  stimulus  that  causes  transitions  between 
modes,  and  the  rationale  by  which  control  data  selections  are  available  at 
each  transition. 

5.3  Functional  Archit^uro 

Describe  the  functional  (or  externally  observable)  behavior  of  the 
program,  including  the  detection  of,  and  recovery  from,  system  failure  and 
input  errors.  Use  hierarchic  rcflnement  of  detail  to  that  level  which  defines 
the  functional  architecture  of  the  program  suSBcient  for  a high-level  design 
review.  Identify  each  function  performed  with  a requirment  in  the  SRD,  or 
else  justify  each  such  function  within  some  set  of  valid  design  criteria. 

The  emphasis  in  this  section  is  on  the  main  sources  and  characteristics  of 
the  input,  the  main  types  and  characteristics  of  output  data,  and  the 
intermediate  flow  through  the  transformational  processes  involved,  for 
funGtional  definition  and  requirement  interpretation,  rather  than  for 
detailed  procedure/ program  control,  the  subject  of  Section  5.4. 

5.4  Procedural  Architecture 

Provide  a leVel-1  flowchart  (or  equivalent)  and  narrative  that  discusses 
the  entire  program  algorithm  and  each  fiinctional  step.  Correlate  operative 
modes  and  external  functional  behavior  elements  with  functions  or  partial 
functions  associated  with  each  procedural  step.  Expand  functions  to  be 
hierarchically  refined  (“striped”  or  “named”  modules)  at  succeed-.ig  levels, 
using  the  standards  given  in  Chapter  12,  to  that  level  of  refinement 
required  to  give  credence  to  cost/schcdule/manpower  estimates,  to  define 
the  program  structure,  aiid  to  illustrate  the  design  and  dOGumentation 
standards  that  will  appear  in  the  SSD.  Correlate  functions  that  operate  on 
major  data  bases  and  internal  data  structures  with  material  in  Section  5.5. 

If  it  is  an  appropriate  design  consideration,  state  what  language(s)  will  be 
used  for  coding  and  why. 
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5.5  Data  Architecture 

Identify  and  describe  the  major  data  bases  accessed  or  created  by  the 
program  being  developed  and  identify  and  describe  major  data  structures 
used  within  the  program.  Describe  only  the  high-level  design  considerations 
of  such  data,  hierarchically  refined,  as  dictated  by  the  functional  and 
procedural  descriptions  in  Sections  5»3  and  5.4.  In  some  cases,  the  baseline 
design  core  map  may  serve  to  illustrate  memory  requirements  or 
constraints.  Include,  as  appropriate,  considerations  for  data  collection, 
conversion,  and  distribution,  insofar  as  these  are  design  concerns  that 
impact  cost  and  sehedulfe. 

6.  TEST  AND  ACCEPTANCE  ARCHIFECTURE 


6.1  Developinent  Testing  Plan 

State  procedural  guidelines  to  be  used  by  the  development  team  in 
evaluating  program  correctness  prior  to  acceptance  testing.  Discuss  the 
projected  adequacy  of  such  methods  to  reduce  program  errors  prior  to 
verification  (aceeptanee)  testing, 

6.2  Acceptance  Test  Plan 

Identify  plans,  procedures,  configurations,  support,  and  personnel  deemed 
necessary  for  acceptance  testing,  both  in  response  to  the  SRD  and  as 
prompted  by  considerations  recognized  in  the  architectural  design  phase. 
Identify  testing  and  reviewing  personnel. 

6.3  Quality  Assurance  Plan 

Identify  the  level  and  type  of  involvement  by  QA  personnel  during  the 
project  prior  to  delivery.  Identify  specific  functions  and  services  that  QA 
personnel  are  sought  to  provide  (e.g.,  audits  of  performance  vs. 
requirements,  code  vs.  requirements,  code  vs.  flowcharts,  testing  the 
program,  etc.),  and  state  what  materials  will  be  provided  for  QA  action. 

7.  APPENDICES 

Appendices  may  include,  but  are  not  limited  to,  explanatory  material  of 
an  auxiliary  nature,  inserted  directly  or  bound  separately  for  convenience. 
The  following  topics  are  typical.  Appendices  may  be  designated  as 
“Appendix  A,”  etc.,  if  desired,  rather  than  by  the  Dewey-decimal  system 
given  h^re. 

7.1  Glossary 

Provide  a glossary  of  all  acronyms  or  mnemonics  and  all  frequently  used, 
unfamiliar  terms  used  in  the  s6d.  Give  short  definitions  of  each,  and  a 
reference,  when  appropriate,  to  a fuller  definition  in  the  text 
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7.2  References 

Provide  a list  of  all  source  documents,  standards,  procedures,  text  books, 
eta,  used  as  reference  material  in  the  SDD  text.  Give  a short  description  of 
the  infonnation  referred  to  in  each,  if  not  evident  from  the  title* 

7.3  Program  Analyses 

Include,  as  appropriate,  any  program  analyses  that  may  tend  to  support, 
illustrate,  clarify,  or,  in  some  cases,  refine  the  material  or  rledsions 
contained  in  the  S0D.  For  example,  a decision  to  code  the  ^sigii  in 
assembly  language  may  be  support^  by  a timing  iinalysis  of  critical,  high- 
priority  external  functions  that  can  only  be  acGOumiodated  in  assembly 
code.  The  results  of  coding  and  testing  the  architectural  pGrtion  of  the 
desi^  (using  dummy  stubs)  may  be  ofifered  in  evidence  of  correctness,  eta 

7.4  Formats  and  Auxiliary  Tables 

tf  formats  or  other  auxiliary  tables  have  been  established  by  this  SDD 
and  are  appropriate  appendix  material,  include  these  in  this  section. 
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This  appendix  contaias  a detailed  outline  for  the  accumulation  of  all 
program  specifications  into  a single  document.  The  items  listed  are  not 
meant  to  he  filled  out  in  the  order  listed  as  a function  of  time.  Rather, 
different  sections  should  be  worked  on  as  they  are  appropriate  to  the 
program  development  effort.  The  outline  given  then  organize*;  that  material 
into  logically  related  sections  for  readability.  On  completion,  the  document 
forms  the  as-built  specification  of  the  program,  and  serves  as  the  principal 
maintenance  document. 

Figure  E-1  is  a top-level  view  of  the  document  organization;  greater 
hierarchic  detail  is  provided  in  the  detailed  outline  that  follows.  The 
outline  contains,  after  each  topical  heading,  a description  of  the  type  of 
material  to  he  inserted  at  that  point. 

The  level  of  detail  in  the  SSD  may  vary  according  to  the  documentation 
needs  of  the  program.  The  topics  given  are  meant  to  serve  as  a 
documentation  checklist.  Tn  full,  the  topics  constitute  Class  A documenta- 
tion detail. 

Much  of  the  material  cited  herein  for  inclusion  can  perhaps  be  satisfied 
by  references  to  suitable  documentation  elsewhere,  or  by  attachment  to  this 
SSD.  Such  practice  should  he  encouraged  whenever  the  reference 
documents  are  either  stable  or  under  the  .same  change  control  mechanism 
as  this  SSD,  or  else  when  any  instabilities  or  changes  in  those  references  are 
not  apt  to  affect  the  “as-built”  character  of  this  specification. 


Chapters  11  aiid  12  contain  more  specific  and  detailed  information 
relative  to  completion  of  the  SSD. 
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SOFTWARE  SPECIFICATION 
DOCUMENT 

Detailed  Table  of  Contenta 


FRONT  MATTER 

Title  Page.  Provide  a title  page  containing  (l)  document  number;  (2) 
SOFTWARE  SPECIFICATION  DOCUMENT;  (3)  program,  subsystem, 
and  system  titles;  (4)  the  publication  date;  (5)  a signature  approval  block 
appropriate  for  the  management  authority  level  required;  and  (6)  releasing 
organization.  Signatures  are  to  be  supplied  only  at  SSD  completion,  The 
date  reflects  the  time  of  last  change  to  any  item  in  the  SSD. 

Abstract  Give  a brief  abstract  that  summarizes  the  program  specification. 

Change  Control  Information.  Provide  a statement  that  speciflec  the 
current  level  of  change  control  authority  during  production,  and  procedures 
for  updates.  On  completion,  revise  this  iiiformation  to  reflect  the  proper 
post-signature  change  control  policy  and  procedure. 

Distribution  List.  Provide  a distribution  list  of  all  parties  with  need-to- 
know  status  of  the  final  complete  SSD  who  are  to  receive  copies. 

Distribution  Information.  Provide  a statement  that  tells  how  additional 
copies  may  be  obtained. 

Table  of  Contents.  Provide  a detailed  table  of  contents  for  the  S$D,  which 
lists  section  number,  title,  and  page  of  eveiy  item  with  a heading*  This  item 
is  probably  the  last  supplied  to  the  SSD, 


TEXT  OF  SPECIFICATION 


1.  INTRODUCTION 

1.1  Purpose  of  the  Program 

Provide  a brief  statement  of  the  purpose  of  the  program  and  of  this 
specification. 
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1.2  Scope  of  Applicability 

Describe  the  scope  of  the  document*  including  brifef  statements  about 
eaeh  major  section  of  the  document,  if  necessarj^. 

1.3  Applicable  Documents 

List  Gontrolling  and  source  documents  that  apply  to  this  speeiflcation, 
such  as  the  SRD,  SOM,  user  manuals,  external  functional  or  programming 
specifications,  etc. 

14  System/Subsystem  Overview 

Identify  the  general  system,  subsystem,  and  environment  (hardware  and 
software)  in  which  the  program  operates  (a  block  diagram  with  narrative  is 
useful  here).  Also,  state  the  general  system/subsystem  operating  mode,  such 
as  *'interruptrdriven,  real-time,  on  dedicated  MODCOMP  operating  under 
MAX/HI  with  16K-word  core  and  5M-byte  disk/'  Identify  any  other 
general  system  constraints  imposed  by  requirements  that  influenced  design, 
such  as  allocated  core  size,  system^imposed  timing  constraints,  etc.  Leave 
details  describing  the  system /siibsystem  to  Section  3, 

1.5  General  Description  of  the  Program 

Provide  a general  functional  description  of  the  program,  including  the 
nature  of  the  problem  and  the  type  of  data  generated,  processed,  or 
transmitted.  Identify  the  type  of  program,  such  as:  (l)  real-time,  interactive, 
Dr  batch;  (2)  computational  or  data  manipuiationi;  (3)  developmental  or 
operational  If  appropriate,  describe  the  method  of  solution. 

2.  STANDARDS  AND  CONVENTIONS 

This  section  describes  standards  and  conventions  used  in  this  SSD  and  in 
programming,  to  describe  both  the  internal  and  external  characteristics  of 
the  program. 

2.1  Specification  Standards  and  Conventions 

2. 1 .1  Applicable  Documentation  Standards 

Identify'  all  existing  doeumentation  standards  that  are  used  to  document 
the  program  as  appropriate  references  to  Section  7.2  of  the  SSD. 

2.1.2  Exceptions  to  Specified  Documentation  Standards 

Identify  all  exceptions  to  the  standards  specified  in  2,1,1,  above,  and 
provide  alternate  standards  in  their  stead,  if  required, 

2.L3  Special  Documentation  Standards 

Describe  any  special  standards;,  such  as  formats  for  graphics  (e.g.,  Petri 
diagrams)  or  descriptions  of  data  structures  (e.g.,  by  a PASCAL-like  syntax), 
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that  are  not  covered  by  standards  above.  Define  special  terms  or  symbols, 
especially  those  used  in  non-standard  ways,  or  in  ways  that  are  likely  to  be 
misunderstood  by  envisioned  readers. 


2J2  Programming  Standards 

This  section  describes  standards  and  conventions  used  to  implement  the 
program  and  to  document  the  program  internal  characteristics. 

2.2.1  Applicable  Policy  and  Procedure  Docuinents 

Identify  appropriate  policy  and  procedure  documents  that  govern  the 
program  implementation  philosophy^  discipline,  or  approach  by  appropri- 
ate reference  to  Section  7.2  of  the  SSD. 

2.2.2  Exceptions  to  Established  Policies  and/or  Procedures 

Identify  extensions,  modifications,  additions,  or  other  exceptions  to  the 
documents  listed  in  2.2.1,  above,  if  needed. 

2.2.3  Special  Policies  and  Procedures 

Describe  any  special  policies  applied  toward  the  development  of  this 
program  not  covered  by  Sections  2.2  i and  2.2.2,  above. 

2«2.4  Applicable  Programming  Standards 

Cite  any  existing  programming  standards  used  by  appropriate  reference 
to  Section  7.2  of  the  SSD. 


2.2.5  Exceptions  to  Specified  Programming  Standarils 

Identify  all  exceptions  to  cited  standards  in  2.2.1,  above,  and  state 
alternate  standards  used  in  their  stead,  if  required. 

2^2.6  Special  Programming  Standards 

Describe  any  special  standards  adopted  for  this  program,  such  as:  (l) 
register  definitions  and  usage;  (2)  naming  of  variables  or  program  labels;  (3) 
assumed  form  of  subroutine  calling  sequences  and  other  procedural 
linkages;  (4)  use  of  global  macros;  (5)  naming  of  compile-time  constants 
and  parameters;  (6)  method  used  to  prevent  inadvertent  misuse  of  program 
resources,  e.g.,  as  duplication  of  variable,  file,  aiid  label  names;  (7)  method 
used  for  arbitration  of  requests  for  use  of  shared  resources;  (8)  method  used 
to  assure  that  deadlocks  cannot  occur;  etc. 

2.2.7  Programming  Language(s) 

Indicate  the  specific  language(s)  used  and  any  language  extensions 
allowed,  including  macros,  when  applicable. 
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2.3  Test  and  Verification  Standards 

2.3«1  Applicable  Test  and  Verification  Standards  Documents 

Identify  all  standards  documents  that  are  applicable  to  the  establishment 
of  program  correctness  and  to  the  demonstration  of  acceptance  criteria  by 
appropriate  reference  to  Section  7.2  of  the  SSD. 

2.3«2  Exceptions  to  Specified  Test  and  Verification  Standards 

Identify  all  exceptions  to  the  standards  specified  in  2,3.1,  above,  and  state 
alternate  standards  in  their  stead,  if  required. 

2.3.3  Special  Test  and  Verification  Standards 

Describe  any  special  testing  standards,  such  as  method  of  assessing 
correctness,  reporting  and  archiving  test  data,  benchmark  tests,  etc. 

2.4  Quality  Assurance  Standards 

2.4.1  Applicable  QA  Standards 

Identify  ail  existing  QA  standards  documents  that  are  applicable  toward 
inspection  for  transfer  to  operation  by  reference  to  Section  7,2  of  the  SSD. 

2.4.2  Exceptions  to  Specified  QA  Standards 

Identify  all  exceptions  to  the  standards  specified  in  2.4.1,  above,  and  state 
alternate  standards  in  their  stead,  if  requir^. 

2.4.3  Special  QA  Standards 

Describe  any  special  standards,  such  as  rules  for  cross-auditing  narrative, 
flowcharts,  code,  and  test  results,  or  for  auditing  narrative  format, 
flowchart  conventions,  indentations  or  annotation  of  code,  decision  table 
formats,  etc. 


3,  ENVIRONMENT  AND  INTERFACES 

3.1  Syatem/Subsy^em  Description 

3.1.1  Applicable  System  Documents 

Reference  those  source  documents  and  manuals  listed  in  7.2  that  describe 
the  general  interface  characteristics  of  the  ^tem  or  subsystem  in  which  the 
program  resides. 

3.1.2  General  Description  of  System /Subsystem  Environment  and 
Interfaces 

Identify  the  system/subsystem  interfaces,  and  describe  the  program  and 
system  environment  in  an  introductoiy  manner,  for  further  detailing  in 
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appropriate  subsections  of  this  section;  Use  the  narrative  in  this  subsection 
to  expose  the  reader  to  the  material  contained  in  the  coming  subsections, 
ami  to  guide  him  verbally  toward  a general  understanding  of  the  material 


3*2  Hardware  Characteristics  and  Conatralnta 

Identify  and  describe  the  pertinent  hardware  functionally.  However,  defer 
detailed  descriptions  of  haidware  items,  using  references  to  specifications 
documents  and  tecluiical  manuals  listed  in  Section  7.2  of  the  SSD  whenever 
possible,  if  not  covered  in  3,1.1,  above.  Otherwise^  supply  such  information 
in  Sections  3, 2.1-3,2. 7,  below,  as  appropriate^ 

3*2.1  General  Description  of  the  Hardware 

Provide  a narrative  description  of  the  pertinent  aspects  of  the  hardware 
in  which  the  program  operates,  including  functional  diagrams,  as 
appropriate. 

3.2*2  Machine  Configuration 

Include  a block  diagram  of  the  main  frame  and  peripheral  configumtion, 
if  appropriate. 

3.2.3  Main-Frame  Characteristics 

Identify  those  main-frame  characteristics  that  are  pertinent  to  the 
software  design,  such  as:  (l)  read-only  memoiy,  (2)  floating  point  hardware, 
(3)  allocated  core  size,  etc. 

3.2.4  Peripheral  Characteristics 

Identify  the  type  and  quantity  of  standard  peripherals  accessed  by  the 
program.  Describe  any  peripheral  characteristics  that  are  pertinent  to  the 
software  design. 

3.2.5  User/Operator  Control  Interface  Characteristics 

3.2.5. 1 Control  Input  Devices 

Identify  all  input  devices  utilized  for  control  of  the  program,  such  as:  (l) 
keyboard,  (2)  card  reader,  (3)  control  panel,  (4)  special  devices. 

3.2.5.2  Control  Monitor  Devices 

Identify  all  output  devices  utilized  for  responding  to  controls,  such  as:  (l) 
fypewriter,  (2)  CRT / hard  copy,  (3)  line  printer,  (4)  control  panel,  (S)  special 
deviGes. 

3.2.5. 3 Control  Device  Gl\aracteristics 

Identify  any  special  eharaeteristics  of  control  devices,  such  as:  (l)  ASCII, 
EBCDIC,  or  Fiddata  character  codes;  (2)  line  rates;  (3)  half  duplex  or  full 
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duplex;  (4)  ^stem-imposed  characteristics*  ag.,  data  transfer  mode  by 
character  or  by  block. 

3*2i6  User/Operator  Data  Interface  Characteristics 
3.2«6.i  Data  Input  Devices 

Identify  all  output  devices  utilized  by  the  user/operator  for  data  input  to 
the  program,  such  as:  (l)  keyboard.  (2)  card  reader.  (3)  control  panel.  (4) 
special  devices. 

3.2.6.2  Data  Output  Devices 

Identify  all  output  devices  utilized  for  data  output  from  the  program  to 
the  user/operator,  such  as  (l)  typewriter.  (2)  GRT/hard  copy,  (3)  line 
printer,  (4)  card  punch,  (o)  plotter,  16)  special  devices. 

3.2»6.3  Data  Input/Output  Device  Characteristics 

Identify  any  special  characteristics  of  user/operator  data  input/output 
devices,  such  as:  (l)  ASCII,  EBCDIC,  Fieldata  character  codes;  (2)  line 
rates;  (3)  half  duplex  or  full  duplex;  (4)  automatic  control  codes  or  other 
non-printing  control  characters. 

3.2.7  Data  Storage  Device  Interface  Characteristics 

3.2.7.1  Data  Storage  input/Output  Devices 

Identify  all  mass-storage  devices  utilized  for  data  or  control  inputs  and 
outputs  to  the  program,  such  as:  (l)  disk/drum,  (2)  magnetic  tapes,  (3) 
paper  or  cassette  tape.  (4)  other  mass  memory  devices. 

3.2.7.2  Data  Storage  Device  Characteristics 

Identify  any  special  characteristics  of  mass-storage  devices,  such  as:  (l) 
minimum  sector  size  of  dislc/drurn,  (2)  number  of  tape  recorder  tracks,  (3) 
tape  blocking  factor.  (4)  ASCII,  EBCDIC,  or  Fieldata  character  codes. 


3*3  Software  Environment 

Provide  a narrative  description  of  the  system  software  that  imposes 
constraints  on  the  program  design.  Identify  the  compiler{s)  or  assembfer(s) 
used,  by  version  if  necessary,  and  the  mode  of  operatidn^  such  as  batch, 
miiltiprogram  interaGtive,  background  batch,  etc.,  if  appropriate.  Do  not 
enter  information  that  does  not  have  a direct  bearing  on  the  design.  If 
necessary,  however,  supply  such  information  in  Sections  3.3.1-3.3.3,  below. 

3,3,1  General  Description  of  System  Software 

Describe  the  general  organization  of  system  software,  with  diagrams  as 
appropriate. 
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3.3.2  Interaction  With  the  Operating  System 

Describe  how  the  program  interacts  with  the  operating  system,  and 
describe  any  special  features  of  the  operating  system  to  accommodate  this 
design. 

3.3.3  interaction  With  Other  Programs 

Describe  how  the  program  interacts  with  other  programs,  including 
library  calls  for  standard  subroutines,  program  linking/overlaying,  and 
those  operating  in  a multiprogramming  environment,  if  not  adequately 
described  elsewhere  in  the  SSD. 

3.4  luterfaDe  Characteristics 

3.4.1  Operating  System  Interfaces 

Provide  a description  of  operating  system /program  interfaces,  or  give  a 
reference  to  such  material  elsewhere  in  the  SSD,  or  to  a document  listed  in 
Section  7.2. 

3.4.2  Interfaces  With  Other  Programs 

Provide  descriptions  of  interfaces  with  other  programs  or  give  a 
reference  to  such  material  elsewhere  in  the  SSD,  or  to  a document  listed  in 
Section  7.2.  Identify  programs  that  provide  data  to  or  receive  data  from  the 
program.  Identify  any  special  characteristics  related  to  the  data  transfer 
between  programs.  Define  the  parameters  for  data  messages  and  the 
characteristics  of  data  control  parameters  associated  with  the  data. 

3.4.3  External  Hardware  Interfaces 

Identify  all  non-standard  or  specialized  input/output  devices.  Define  the 
pertinent  characteristics  of  these  devices,  such  asi  (l)  control  parameters, 
(2)  response  parameters,  (3)  interrupts,  (4)  interrupt  priority,  (5)  timing' 
constraints.  Tf  such  information  exists  in  a source  document,  it  may  be  more 
appropriate  to  cite  such  a reference  than  to  repeat  that  information  here. 

3.5  Suppe^ing  Programs 

Describe  or  give  a reference  to  any  programs  used  for  operational  or 
developmental  support  of  this  program,  if  such  descriptions  are  needed  to 
understand  the  program  specifications  herein  contained.  In  such  cases, 
describe  the  interfaces  and  interactions  with  such  programs. 

4.  SOFTWARE  FUNCTIONAL  SPECIFICATION 

4.1  Functional  Organization  and  Overview 

Describe  the  overall  functional  behavior  of  the  program,  the  principal 
modes  of  operation,  the  different  software  configurations  (if  any),  and  major 
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data  flows.  Cite  applicable  requirements  documents  and  user/operator 
manuals  by  appropriate  references  to  Section  7.2  of  the  SSD.  The  object  of 
this  section  is  to  prepare  the  reader  for  the  detailed  functiona! 
specifications  to  follow.  In  this  overview,  discuss  the  general  philosophy 
concerning  detection  of  and  recovery  from  system  failure  and  input  errors; 
if  needed,  attach  these  as  appropriate  Sections  4.1.  > nnd  4.1./  (i  and  / are 
appropriate  numerals  within  4,X),  as  detailed  below. 

4.1.1  Detection  of  and  Recovery  From  System  Failure 

Describe  the  technique  to  be  used  to  detect  and  recover  from  system 
failure,  such  as:  (l)  re-run  program,  (2)  writing  of  checkpoint  recovery  fiife, 
(3)  storing  data  on  disk  and/or  tape  at  specified  intervals,  (4)  backup  system 
on  line,  etc. 

4.1.j  Detection  of  and  Response  to  Data  Input  Errors 

Describe  the  extent  to  which  input  data  is  to  be  verified  before 
processing,  and  the  verification  method,  such  as;  (l)  checksums  on  data 
records  or  files,  (2)  error  detection  coding  and  retransmission,  (3)  message 
to  operator  for  man^ial  verification,  etc. 

4.2  Detailed  Software  Configurations  and  Modes  of  Operation 

Identify  each  of  the  different  software  configurations  (essencialfy  different 
programs  built  or  linked  together  as  a unit).  For  each  configuration, 
identify  the  various  operational  modes  (program  functions  that  change  as  a 
result  of  the  operational  state  or  control  data).  Describe  events,  conditions^ 
or  computations  that  cause  transitions  between  modes.  Use  hierarehic 
refinement  if  modes  have  functional  submodes  that  need  description.  Name 
and  number  each  mode  for  input-processing-output  descriptions  in  SSD 
Section  4.3.  Use  decision  tables  to  express  mode-transition  logic  and  to 
identify  major  functions  within  modes  as  appropriate. 

4.3  Input,  Processing,  and  Output  Specifications 

This  section  contains  hierarchiGally  refined  input-processing-output 
specifications  and  deals  with  end-to-end  program  functional  characteristics. 
Each  major  Subsection  4.3.  f,  below,  where  i Js  a function  or  mode 
identifier,  describes  one  of  the  program  modes,  and  subsections  within  these 
refine  the  various  aspects  of  the  mode  functional  behavior. 

4.3.1  Function  i Nfodc  (or  Mode  i)  Inpiit-Processing-Output 

Describe  the  inputs  to  this  mode,  the  processing  functions  performed  qn 
the  input,  and  resultant  outputs  and  responses.  Illustrate  the  mode  inputs, 
functions,  and  outputs  by  a one-page  data  flow  diagram,  and  explain  the 
program  behavior.  Use  decision  tables  to  define  responses  to  intricate 
logical  conditions^  Further  informat'  :»n  on  generating  siich  sections  of  the 
SSD  is  contained  in  Chapters  11  and  12. 
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4.4  User/Qperator  Functions  end  Special  Features 

Identify  and  summarize  the  user/operator  interfaces  and  specify  those 
functions  performed  by  the  user/qperator.  Alternatively,  give  a reference  to 
the  appropriate  user/operator  manual  Hsted  in  Section  7.2  of  the  SSD.  If  a 
reference  is  given  to  such  a manual  in  lieu  of  specifying  operator  functions 
here,  then  that  manual  becomes  the  operator  functional  specification,  and 
should  also  be  brought  under  the  same  change  control  mechanism  as  this 
specification. 


4.4.1  Control/Response  Message  Parameters 

For  the  input/output  devices  listed  in  Section  3.2.5,  define  control/ 
r^ponse  message  parameters,  such  as:  (l)  structure  and  format  (reference 
7.7.1),  !2)  syntax,  (3)  message  lengths  and  frequency,  (4)  device  assignment 
codes,  (5)  special  timing  constraints,  (6)  special  features  such  as  access  keys, 
passwords,  or  lockout  keys,  etc. 

4.4.2  Data  Input/Output  Message  Parameters 

For  the  data  input/output  devices  listed  in  Section  3.2.6,  define  user/ 
operator  data  input/output  message  parameters,  such  as:  (l)  structure  and 
format  (reference  7.7.2),  (2)  syntax,  (3)  message  lengths  and  frequency^  (4) 
device  assigi^merit  by  message,  (S)  special  considerations  such  as  online  vs. 
oSline  ptiiiting/display,  (6)  data  units,  (7)  data  ranges,  etc. 

4.4.3  Operational  Environment  and  Support 

Provide  specifications  for  any  operational  support  required  for  this 
program,  and  state  any  operational  environmental  characteristics  on  which 
the  specification  of  this  program  is  based,  beyond  normal  or  standard 
operational  facilities,  or  give  a reference  to  documents  listed  in  7.2  that 
provide  such  information. 

4.4.3. 1 Operator  Functions 

Specify  other  user/operator  interactions  required  for  operation  of  the 
program,  and  discuss  any  pertinent  considerations  for  offline  activities,  such 
as  transmittal  or  storage  of  output,  operations  log,  etc,,  as  appropriate. 

4.4«3.2  Special  Functions 

Specify  any  other  operational  support  functional  requirements,  such  as 
criteria  for  running  backup  operational  programs  or  re-entry  of  checkpoint 
data,  etc. 
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4.5  Data  Bate  Specificeitiona 

4,5*1  Interaction  With  Extemal  Data  Bases/File$ 

Describe  or  give  appropriate  references  to  Section  3.3  of  the  SSD  that 
state  how  the  program  interacts  with  data  bases  and  files  which  are  extemal 
to  the  program.  Where  appropriate,  give  data  block  formats^  table  formats, 
calling  sequences,  message  formats,  relationships  between  fields  oi*  records, 
units  of  measure,  conversion  formulas,  etc, 

4.5.2  Creation,  Access,  and  Maintenance  of  Extemal  Data  Bases/Files 

Indicate  whether  or  not  data  bases  and  files  extemal  to  the  prograni  are 
created  and/or  maintained  by  this  program.  Discuss  matters  of  privacy, 
security,  and  integrity  of  such  data  bases, 

4.5.3  Applicable  Data  Base/Fite  Documentation 

Reference  those  source  documents  listed  in  Section  7.2  of  the  SSD  that 
describe  the  pertinent  data  bases  or  data  files,  including  those  documents 
which  describe  how  the  data  bases  or  files  are  created  and/or  maintained. 

4.5.4  Data  Base  Descriptions 

If  there  are  no  applicable  documents  referenced  by  Section  4.a3,  above, 
or  if  further  specification  is  warranted  in  this  SSD,  provide  that  information 
In  this  section.  Formats  may  be  put  in  appendices.  Section  7.7,3. 

5.  PROGRAMMING  SPECIFICATION 

5.0  Program  Overview 

Describe  and  discuss,  in  summary  form,  the  solution  method,  the  overall 
program  organizationi  major  internal  data  structures,  and  major  algorithms 
that  constitute  the  main  program  funGtioris.  Give  design  philosophy  and 
rationale  as  appropriate  for  understanding,  and  give  referencfEfS  to  program 
analyses  in  Sect  ion  7.5,  if  any,  which  are  pertinent  to  the  overall  program 
description. 

The  sections  under  this  topical  heading  may  describe  relationships 
between  the  functional  behavior  and  the  executing  modules  of  the  program, 
i.e.,  an  analysis  of  what  modules  do  which  functiohs>  Other  subsections  nity 
describe  and  depict  data  flow  between  executing  modules  or  concurrent 
processes  to  illustrate  how  the  program  architecture  accoinmodates  the 
functional  specifiGation.  Still  other  subsections  may  discuss  the  roles  played 
by  the  various  modules  in  each  of  the  several  program  modes,  or  may  show 
various  data  interface  charaGteristics,  when  appropriate  at  this  highrleveK 
design  overview. 
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Insert  Sections  5;0J  and  5.0./,  below,  which  discuss  design  philosophy 
and  competing  characteristics,  at  appropriate  points  i and  / in  the 
overview. 

5.0J  Design  Philosophy  and  Rationale 

Include  a brief  description  of  the  design  philosophy,  disGipline*  or 
approach  taken  In  the  program  hnplementation,  and  give  rationale  as 
appropriate  to  explain  such  descriptions,  insofar  as  such  descriptions  tend 
to  explain  why  the  design  appears  as  it  does. 

Ordered  Set  of  Competing  Characteristics 

Describe  the  general  order  of  priorities  adopted  to  fulfill  the  design 
philosophy.  Include  an  ordered  list  or  table  of  factors  that  compete  for 
resources,  such  as:  (l)  program  size;  (2)  execution  speed;  (3)  cost  to 
implement;  {4)  time  to  implement;  (5)  vulnerability  to  operator  error;  (6) 
maintainab*';:y;  (7)  growth  capability,  including  extension;  (S)  portabili^, 
or  machine  independence;  (9)  cost  to  operate;  (lO)  readability  of 
documentation;  (ll)  coneurrency  of  doeumentation;  (12)  vulnerability  to 
system  errors;  etc* 

5(1)’^  Main  Program  Detailed  Design  (Module  1) 

Provide  an  algorithmic  description  of  the  top-level  main  program  design, 
as  described  in  Chapter  12.  Hierarchic  detailings  of  the  main  program  into 
nested  1-page  flowcharts  with  accompanying  narratives  (or  equivalents) 
then  follow  as  subsections. 

5(n)  Configuration  ri  Detailed  Design  (Module  n) 

If  the  program  has  different  identifiable  compile  conflguratiolfe,  show 
each  such  configuration  beginning  at  its  top-level  flowchart  and  narrative, 
as  above.  Numeric  identifiers  can  also  be  used  for  major  program  segments 
within  a program,  if  desired. 

5(S)  Internal  Subroutine  Detailed  Designs 
5(Si)  Subroutine  I Detailed  Design  (Module  Si) 

Provide  a detailed  algorithmic  description  of  the  topdevel  design  of  each 
Subroutine  i,  as  described  in  Chapter  12.  Hierarchic  detailings  of  each 
subroutine  procedure  into  nested  1-page  flowcharts  with  aceompanying 
narratives  (or  equivalents)  then  follow  as  subsections. 


* Numbers  in  parentheses  refer  to  Dcwcy-deciinal  identifiers  for  flowcharts,  data^structure 
delinitiomif  or  resource  allocation.  rcqMircmenb!. 
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S{X)  External  Subroutine  Interface  Descnptiom 
9(Xi)  External  Subroutine  i Inleiface  Description 

Each  section  such  as  this  in  the  SDD  shall  provide  the  necessary  interface 
description  for  an  external  module  called  by  this  program  being  specified 
Such  description  shall  contain,  but  shall  not  be  limit^  to:  (l)  the  purpose 
and  function  of  the  subroutine;  (2)  the  calling  sequence;  (3)  all  extenial 
programs  and  subroutines  called;  (4)  common  data  areas;  (5)  operating 
system  interface  data;  (6)  mathematical  equation,  if  appropriate;  (?) 
execution  speed  and  core  usage,  if  relevant;  (S)  input/output;  (9) 
restrictions  for  use;  and  (10)  error  messages.  If  suitable  descriptions  of  this 
type  are  documented  elsewhere,  then  a reference  to  such  source  material 
listed  in  7.2  is  sufficient 

5(Y)  Data  Structure  Definition  iFables 

5(?j)  Data  Structure  Name  j Defiynition  Table 

Each  section  such  as  this  shall  describe  common^  global,  or  shared  data 
struetures.  Such  descriptions  become  the  controlling  interface  definition  for 
all  accesses  to  the  structure,  and,  when  appropriate,  identify  those  functioas 
forming  the  level  of  access  to  the  structure.  Descriptions  shall  contain,  but 
shall  not  be  limited  to:  (l)  mnemonic  name  and  derivation  of  that  name;  (2) 
purpose  and  usage  in  the  program;  (3)  structural  description,  including 
overall  ^e,  size,  component  breakdown,  and  graphic  illustration(s);  (4) 
substructure  definitions.  Including  for  each  field:  type,  size,  position  (if 
relevant),  relations  with  other  components^  allowable  operations,  and 
constraints,  such  as  ranges  of  value;  v5)  functions  or  operations  that  may 
manipulate  the  structure  (or  its  members);  (6)  associated  constants  used  to 
define  structure  parameters;  (7)  relationships  with  other  structures;  and  (8) 
constraints  on  usage. 

5(Z)  Resource  Access  Allocation  Tables 

5(Zlc)  Resource  k Access  Design 

Each  section  such  as  this  shall  describe  access  requirements,  protocols, 
methods  for  achieving  mutually  exclusive  use,  ^chi^onization,  etc.,  for  a 
resource  or  sets  of  resources.  These  descriptions  may  take  the  form  of 
hierarchic  levels  of  access,  described  in  layers  of  refined  detail  in 
subsections  of  each  such  section. 

& TEST  AND  VERIRCATION  SPEGIFICATIONS 
6*1  Production  Testing 

This  section  describes  correctness  testing  by  implementors^ 
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6«1.1  Applicable  Existing  Production  Test  Procedures 

Identify  by  appropriate  reference  to  Section  7<2  of  the  SSD  any  existing 
and  documenti^  production  testing  procedures  (other  than  standards  in 
Section  2.3)  used  to  support  the  validation  of  this  program  during 
development. 

6Jv2  Excreptions  to  Existing  Production  Test  Procedures 

Identify  all  exceptions  to  existing  test  procedures  referenced  by  Section 

6.1.1,  above^  and  state  alternate  procedures,  when  applicable. 

6.1.3  Other  Production  Test  Procedures 

Define  other  production  testing  procedures  used  to  support  the 
verification  of  this  program  during  development.  Define  criteria  for  test 
data  selection,  and  state  procedures  for  determining  the  validity  of 
observed  program  responses  to  given  test  data.  See  Section  6.2.3,  below,  for 
suggested  ouUine. 

6.2  Acceptance  Test  Specifications 

When  appropriate,  this  section  specifies  tests  that  dei^onstrate  the 
fulfillment  of  acceptance  criteria. 

6.2.1  Applicable  Existing  Acceptance  Test  Procedures 

Identify  by  appropriate  reference  to  Section  7.2  of  the  SSD  any  existing 
and  document^  acceptance  test  procedures  (other  than  standards  in 
Section  2.3)  iised  for  certifying  the  program. 

6.2.2  Exceptions  to  Existing  Acceptance  Test  Procedures 

Identify  all  exceptions  to  existing  test  procedures  referenced  by  Section 

6.2.1,  above,  and  state  alternate  procedures,  when  applicable. 

6.2.3  Other  Acceptance  Test  Procedures 

This  section  defines,  when  appropriate  in  this  document,  other 
acceptance  test  procedures  used  to  certify  the  program  prior  to  operations 
transfer.  Each  subsection  provides  for  the  documentation  of  criteria  for  test 
data  selection  and  procedures  for  determining  the  validity  of  observed 
program  responses  to  given  test  data.  Each  description  shall  contain,  but 
not  be  limited  to:  (l)  an  explanation  of  the  test  objcctiveSi  (2)  test  inputs 
(files,  events,  eta,  or  criteria  for  their  selection),  (3)  test  procedures,  (4) 
support  facilities  required  (used),  (5)  test  conditions  or  eonstraints,  (6) 
outputs  to  be  achieved,  and  (?)  method  of  output  interpretation.  A 
suggested  list  of  considerations  follows. 

6.2.3.1  Verification  of  Program  Control  I/O  Interfaces 

Define  tests  and  techniques  to  verify  proper  operation  of  the  program 
with  the  specified  user/operator  control  media  (Section  3.2.S). 
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6.2.3«2  Verification  of  Program  Data  I/O  Interfaces 

Define  tests  and  techniques  to  verify  proper  operation  of  the  program 
with  the  specified  user/ operator  data  I/O  media  (Section  3.2,6)  and  data 
storage  m^ia  (Section  3.2  J). 

6.2*3. 3 Verification  of  Data  Processing  Functions 

Define  tests  to  verify  proper  operation  of  the  data  processing  functions  of 
the  program.  Include  test  cases  for  normal,  random,  and  abnormal  (out-of- 
range  or  otherwise  unexpected)  data. 

6.2^3.4  Verification  of  Logical  Response  and  Sequence 

Define  tests  and  techniques  to  verify  the  proper  logical  response  and 
sequencing  of  modes  in  response  to  control  and/or  data  input  parameters. 
Include  test  cases  that  verify  responses  to  erroneous  data  or  control 
parameters, 

6.2*3,5  Verification  of  Diagnostic  Functions 

Define  tests  and  techniques  to  verify  proper  operation  of  in-program 
diagnostics  that  aid  the  user/operator  in  dfitteting  failures,  correcting 
errors,  or  in  determining  the  causes(s)  of  abnormal  operating  conditions. 

6*2.3.6  Verification  of  Software  Trap  Action 

Provide  tests  to  verify  proper  operation  of  software  traps  used  to  prevent 
anomalous  operation,  such  as:  (l)  file  record  errors*  (2)  software  timers  for 
endless  loops;  (3)  out-of-range  location  address,  including  out-of-range  of 
available  memory;  (4)  impossible  mathematical  computations,  e.g„  divide 
by  zero, 

6*2.3*7  Verification  of  Error  Response 

Provide  tests  to  verify  that  error  conditions  produce  the  proper 
responses,  such  as  the  correct  error  message. 


6.3  QA  Measures  During  Production 

This  section  defines,  wb^n  appropriate  in  this  document,  the  level  of 
activity  and  responsibilities  of  QA  functions  performed  for  certification  and 
delivery  into  operations,  insofar  as  these  are  not  covered  by  QA  standards 
contained  in  Section  2.4.  Treaty  are  such  areas  as  (l)  procedures  for  an 
audit  of  the  complete  software  package  for  conformance  to  standards,  as 
well  as  conformance  of  code  to  procedural  specifications,  proGediual 
specifications  to  functional  specifications,  functional  specification  to 
requirements,  test  results  to  test  specifications,  and  performance  to 
requii  ^rrtfmts;  (2)  partiGipation  in  design  reviews;  (3)  standards  enforce- 
ment; (4)  configuration  control;  (S)  discrepancy  reporting:  (6)  change 
control;  and  (?)  test  condueting. 
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7.  APPENDICES 

Appendices  may  include,  but  are  not  limited  to,  explanatory  material  of 
an  auxiliary  nature,  inserted  directly  or  bound  separately  for  convenience. 
The  following  topics  are  ^ical.  Appendices  may  be  designated  as 
'‘Appendix  A,**  etc,,  if  desired,  rather  than  by  the  Dewey-decimal  system 
given  here. 

7.1  Glossary 

List  the  names  of  the  program,  all  subprograms  and  subroutines,  and  all 
variables  and  parmneters  used  in  program  design,  along  with  their 
mnemonic  derivation.  Also  give  short  de^itions  of  each  and  a reference  to 
its  detailed  definition,  when  necessary.  Include  all  acronyms,  as  well  as 
frequently  used,  unfamiliar  terms  used  in  the  program  subsystem/system 
descriptions. 

7J2  UsHng  of  Source  Documents  and  References 

Provide  a list  of  all  source  documents,  standards,  procedures,  and 
reference  material  used  for  program  design,  implementation,  and  testing. 
Indicate  the  subject  matter  and  purpose  of  each  reference. 

7.3  Program  Analyses 

Provide  analyses  of  algorithms,  program  functions,  timing  profile 
diagrams,  etc.,  as  appropriate  in  support  of  design  decisions  made  during 
implementation. 

7.4  Sharable  Subroutine  Identification 

Identify  software  items  developed  that  have  sharing  potential,  either  as 
common  software  in  other  subsystems  currently  being  developed  or  as 
candidates  for  use  in  future  implementations. 

7.5  Provisions  for  Future  Modification 

Identify  those  features  of  the  program  that  will  potentially  be  upgraded 
or  modified  in  later  versions,  Describe  provisions,  if  any,  that  have  been 
made  to  facilitate  those  alterations,  and  give  guidelines  how  such 
alterations  can  be  installed  into  the  program, 

7.6  Enror  Message  and  Diagnostics 

Provide  a listing  of  all  error  messages,  the  conditions  that  invoke  each, 
and  the  reason  why  such  conditions  are  improper  (if  not  obvious  from  the 
message). 
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7.7  Detialled  Formats 

7.7.1  Detailed  Cpntrol/Bespoiise  Mesrage  Formats 

Provide  detailed  formats  for  each  control  message,  together  with  the 
r€sponse(s)  to  that  message  as  supplementary  material  to  Section  4.4*1. 

7*7*2  Detailed  Data  Input/Output  Formats 

Provide  detailed  formats  for  data  inputs  and  outputs,  together  with  the 
associated  response(s)  as  supplementary  material  to  Section  4,4*2* 

7.7.3  Data*Base  Input/Output  Formats 

Provide  detailed  formats  for  each  external  data  base  or  hie  used  to  input 
data  to  or  accept  data  from  the  program  when  appropriate.  Identify  each 
format  with  the  corresponding  data  storage  device  listed  in  Section  3*2*7. 
Include  descriptive  data,  such  as:  (l)  number  of  characters  per  file  record, 
(2)  file  data  format,  (3)  number  of  file  records,  (4)  special  end-of-recoid 
marks,  (S)  special  end-of-file  marks,  as  appropriate. 


7.7.3.1  Data-Base  Input/Output  Parameters 

For  the  mass-storage  devices  listed  in  3.2.7,  define  input/output 
parameters,  such  as:  (l)  structure  and  format;  (2)  syntax;  (3)  lengths  and 
frequency;  (4)  device  assignment  by  message;  (o)  special  features  such  as 
access  keys,  passwords,  or  lockout  keys;  (6)  special  timing  constraints;  (?) 
special  considerations  such  as  online  vs.  offline  operation;  (S)  data  units  and 
ranges* 

7.7.3.2  Data  Base  Storage  Device  Data  Control  Characteristics 

Define  the  characteristics  of  data  control  parameters,  associated  with  the 
data,  such  as:  (l)  verification  codes,  (2}  index  tables,  (3)  list  structures* 

7,7.4  Communications  Line  Input/Output  Formats 

Provide  detailed  structure  and  format  of  all  data  blocks  to  be  input  from 
or  output  to  data  communication  circuits,  except  for  data  lines  to/ from 
operator-control  devices  covered  above*  Reference  applicable  documents 
(7*2)  where  appropriate* 


7.8  Auxiliary  Tables 

7.8.1  Detailed  Design  Tables 

Assemble  in  tabular  form  all  auxiliaiy  reference  data  needed  for  program 
specification,  which  is  better  located  in  an  appendix  rather  than  in  the  text 
proper*  Display  each  of  these  as  a separate  subsection,  7*8.  i. 
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Special  Mainterance  f^ocedures 

Identify  any  special  suppotiing  software,  documents,  procedures,  eta, 
used  for  maintaining  the  program,  such  as  for  debugging,  testing, 
verification,  QA,  automatic  redocumentation,  etc.  Give  detailed  proce- 
dures, guidelines,  or  hints  for  maintaining  the  program,  as  appropriatei 
Such  procedures,  if  extensive,  however,  may  well  form  a separate 
Maintenance  Manual,  in  which  case,  only  a citation  to  the  proper  reference 
in  7.2,  above,  need  appear.  See  Appendix  K for  a detailed  set  of  topics. 

7.10  Decision  Log 

Enter  and  discuss  each  of  the  major  design  decisions  that  may  affect 
program  sustaining  and  maintenance. 

7.11  Unkage  Editor  and  Job  Control  Code 

Describe  the  detailed  linkage-edit  code,  job-controJ  code,  or  map 
processing  necessary  to  collect,  load,  and  execute  the  program*  If 
maintenance  procedures  require  altering  this  code,  instruct  the  reader  how 
such  changes  are  to  be  made* 


8.  CODE  LISTINGS 

The  code  listings  form  the  final  part  of  the  “as-built'*  software 
specification.  For  large  programs  the  listings  will  form  a separate  volume* 
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USER  INSTRUCTION  MANUAL  TOPICS 


This  appendix  contains  an  outline  of  topics  typically  considered  for 
inclusion  in  a software  user’s  manual  The  items  listed  are  not  exhaustive, 
nor  are  all  of  those  given  necessarily  applicable  to  a particular  given  user 
guide.  Rather,  the  topics  herein  contained  are  those  that  should  be 
considered  as  candidates  for  inclusion  in  a user  guide  for  a specific 
application.  The  demands  and  needs  of  users,  as  well  as  the  type  and  cost  of 
software  capability  being  exposed,  should  dictate  the  level  of  detail,  the 
arrangement  of  the  material,  the  orientation  of  the  presentation,  and  the 
scope  of  the  content.  The  outline  below  is  an  attempt  at  providing  a 
logically  and  hierarch  ically  arranged  checklist. 

This  text  has  repeatedly  recommended  that  the  user  manual  be  written  at 
least  in  a skeletal  form  frpm^the  top  down  {in  detail  hierarchy)  concurrently 
with  the  writing  of  the  SSD.  hierarchy  and  with  the  construction  of  the 
program,  so  as  to  provide  timely  information  among  developers,  to  permit 
the  user  manual  to  be  tested  concurrently  with  the  program,  and  to  avoid 
last-minute  efforts  to  complete  the  documentation  prior  to  software 
delivery.  The  emphasis  in  writing  the  user  manual  is  on  providing  complete 
and  effective  information  for  exercising  all  of  the  options  and  capabilities  of 
the  program.  The  timely  gathering  of  information  and  writing  technical 
material  for  the  manual,  however,  must  not  be  put  in  series  with  the 
formal,  more  clerical  aspects  (such  as  typing  and  reproduction)  of  a 
documentation  activity^ 


As  the  program  Gom:truction  proceeds  in  a top-down  manner,  usage 
information  in  greater  and  greater  detail  typically  becomes  available.  If 
compiled  and  written  into  the  user  guide  during  this  time,  the  information 
level  will  tend  to  aid  in  assessing  whether  the  emerging  program  falls 
within  its  required  capabilities  implemented  so  far. 
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Figure  F-1  is  a top*levei  view  of  the  suggested  document  organization; 
greater  hierarchic  detail  is  provided  in  the  written  outline  that  follows.  This 
outline  contains  giiidelines  after  each  topical  heading  for  the  type  of 
material  to  be  inserted  at  that  point  In  fulh  the  topics  constitute  Class  A 
detail. 

The  users  of  the  program  assumed  in  this  outline  are  not  envisioned  to  be 
the  operators  of  the  program*  The  user  deterniines  the  feasibility  of  the 
program  to  fulfill  his  needs,  generates  or  prepares  data  (or  causes  it  to  be 
prepared),  submits  it  for  operations  (either  conversationally,  interactively, 
or  in  batch),  and  uses  (interprets)  the  output,  if  any,  for  an  intended  task, 
(in  some  cases,  such  as  where  a user  causes  a data  base  to  be  updated,  that 
output  may  not  be  immediate,  and  may  not  even  be  a result  of  operating 
the  program  being  described;  in  other  cases,  the  task  may  be  the  gaining  of 
insight  into  a problem.) 

A topical  outline  for  the  operational  manual  appears  in  Appendix  I*  In 
cases  where  it  is  desirable  to  combine  both  user  and  operator  Unctions  into 
a single  manual,  the  outlines  can  be  merged  appropriately* 

Sources  for  the  material  contained  herein  are  [44]  and  [45]. 
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Rgure  Graphical  outline  of  the  Uaer  InstructJon  Manual 
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USER  INSTRUCTION  MANUAL 
Detailed  Table  of  Contents 


FRONT  MATTER 

Title  Page.  Provide  a title  page  cGntaining  (l)  document  number;  (2)  USER 
MANUAL;  (3)  program,  subsystem,  and  system  titles;  (4)  the  publication 
date;  (5)  author  and  management  authority  signatures,  as  appropriate;  and 
(6)  releasing  organization.  Signature  or  publication  approval  should  be 
supplied  only  at  SSD  completion.  The  date  reflects  the  time  of  latest 
change  to  any  item  in  the  manual 

Abstract.  Give  a brief  abstract  that  summarizes  the  purpose  and  usage  of 
the  manual 

Change  Control  Tnformatioii.  Provide  a statement  that  specifies  the 
current  level  of  change  control  authority  and  describe  procedures  for 
submitting  change  requests  and  reporting  anomalies. 

Distribution  Information.  Provide  information  that  tells  how  copies  of  this 
document  may  be  obtained. 

Table  of  Contents.  Provide  a detailed  table  of  contents  for  the  manual, 
which  lists  section  number,  title,  and  page  of  every  item  with  a heading 
(this  is  probably  the  list-supplied  item  in  generating  the  manual). 


TEXT  OF  MANUAL 


1.  INTRODUCTION 

1.1  General  Description  of  the  Program  and  its  Use 

Provide  a brief  statement  that  describes  the  purpose  and  use  of  the 
program.  Perhaps  also  appropriate  in  this  introduction  are  background 
information,  history,  relationships  to  other  programs  or  systems,  and  major 
applications  areas. 

1.2  Oriehtation  and  Scope 

Identify  the  intended  readers  of  this  manual,  their  backgrounds^  their 
assumed  levels  of  data-processing  expertise,  and  the  extent  to  which  the 
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content  of  this  manual  is  selfrcontained.  Describe  the  scope  of  the  manual 
as  it  pertains  to  the  usage  of  the  prograin  and  its  products.  Identify  any 
significant  limitations  of  the  program  in  applications. 

1.3  Applicable  Documents 

Identify  all  documents,  controlling  or  informational,  that  apply  to  or 
regulate  the  usage  of  the  program. 

1.4  Program  Overview 

Provide  a brief  functional  description  of  the  program  and  its  intended 
usage,  including  the  nature  of  the  problem  it  solves,  the  philosophy  and 
method  of  solution,  and  the  type  and  content  of  data  input,  processed, 
generated,  or  transmitted.  Identify  the  usage  characteristics  of  the  program^ 
such  as:  (l)  major  applications;  (2)  real-time,  interactive,  or  batch;  (3) 
-computational  or  data  manipulation;  (4)  developmental  or  operational. 
Identify  the  general  system,  subsystem,  and  environment  (hardware  and 
software)  in  which  the  program  operates  (a  block  diagram  is  useful  here) 
insofar  as  these  considerations  affect  usage  of  the  program;  leave  details  to 
Section  3. 

1.5  Guide  to  the  Use  of  the  Manual 

Explain  how  this  guide  is  to  be  used  in  applications. 

2.  STANDARDS  AND  CONVENTIONS 

This  section  describes  the  standards  imposed  on  or  by  the  using 
organization,  and  the  conventions  (e.g.i  notations  and  terminology)  applied 
in  this  manual. 

2.1  User  Organization  Standards 

Identify  or  reference  applicable  existing  organizational  usage  standards, 
state  any  exceptions  to  these  standards  necessitated  by  the  usage  of  this 
program,  and  provide  any  special  standards  required  to  use  the  program 
effectively, 

2.2  Operations  interface  Standards 

Identify  or  reference  existing  standards  that  apply  to  the  user/ operations 
interface,  state  any  exceptions  to  these  standards  (negotiated  as  required  for 
operation  of  this  program),  and  providie  aiiy  special  standards  required  for 
users  to  interface  properly  with  operations, 

2.3  Manual  Conventions 

Define  notations,  terms,  and  other  Gonventions  or  assumptions  used 
generally  throughout  the  manual.  Include  such  items  as  ways  of 
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distinguishing  literal  fields  from  syntactic  variables  in  descriptions  of  input 
and  output  formats,  means  for  differentiating  user  inputs  from  outputs  in 
examples  of  interactive  operations,  non-standard  mathematical  usage, 
special  acronyms^  etc. 


3.  USER  ENVIRONMENT  AND  INTERFACES 


3.1  Data  Flow 

Describe  data  sources  and  sinks,  the  flow  of  data  from  sources  to  sinks, 
and  the  role  the  program  plays  in  this  flow.  Identify  operations,  systems, 
library  and  support  interfaces,  and  describe  their  role  as  seen  by  the  user.  A 
diagram  may  be  useful  for  illustrative  purposes  here. 

3.2  User  Environment 

Introduce  the  general  environment  within  which  the  user  interfaces  with 
the  program.  Identify  interfaces  among  users  (if  any),  location  of  users,  their 
sources  of  data,  the  media  through  which  they  prepare  data,  submit  runs, 
and  receive  output,  their  manual  tasks^  relationsldps  among  data  in  the  user 
environment,  etc.  Describe  user  interfaces  with  management,  if  approprir 
ate.  Drfer  user  procedures,  specific  formats,  units,  etc.,  until  later  sections. 

3.3  Operational  Interfaces 

Identify  and  describe  the  interfaces  between  the  program  user  and  the 
program  operational  environment  Discuss,  as  appropriate:  forms,  input 
media,  control  media,  interfacing  procedures,  data  generation  methods, 
storage  media,  modes  of  delivery  of  output  to  users,  manual  tasks,  etc* 
Identify  those  items  that  are  unique  to  this  program  and  not  covered  by  an 
overall  system  description  or  governing  document  (if  this  manual  need  not 
be  self-contained).  Defer  operational  procedures,  formats,  units,  etc.,  to  the 
operational  manual  (Appendix  t)^  unless  user  and  operational  guides  are 
combined  in  one  manual. 

3.4  Data  Base  and  Library  interfaces 

3*4.1  Data  Base  Interfaces 

Describe  all  data  files  in  the  data  base  that  are  referenced,  supported,  or 
kept  current  by  the  program,  insofar  as  these  are  visible  to  users  of  the 
program.  Include  the  purpose  of  each  such  file,  but  defer  detailed  formats 
(if  necessaiy  for  use)  to  an  appropriate  appendix.  If  there  are  offline  or 
manually  maintained  parts  of  the  data  base  that  are  pertinent  to  the  usage 
of  this  program,  rimilarly  describe  these  elements* 
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3*4,2  Library  Interfaces 

Describe  any  appropriate  user  interactions  or  interfaces  with  document 
libraries,  software  (program^  subprogram)  libraries^  dr  offline  storage 
libraries  other  than  those  describe  in  the  operational  interfaces  above. 
Reference  source  documents  for  data  preparation  and  editing  aids,  output 
data  monitor  and  diagnostic  aicS;  etc* ^as  applicable. 

4.  FEATURES  OF  THE  PROGRAM 

This  entire  section  documents  the  end-to*end  functional  characteristics 
and  usage  of  the  program,  to  a level  of  detail  sufficient  for  stand-alone 
reference*  This  s^tion  should  describe  each  functional  capability  and 
option  of  the  program  fully,  giving  examples  of  each,  annotated  and 
explained*  Usage  of  graphic  material  in  explanations  is  encouraged* 

4.1  Functionat  Overview  and  Capabltitl^ 

Prior  to  detailed  usage  characteristics  in  the  other  subsections  of  this 
section,  present  an  overview  of  program  capability.  Typical  co^'erage  at 
this  point  might  address  the  structure,  I/O  and  data  flow,  functional 
categories,  range  of  r^ppUcations,  major  operating  modes,  program 
configurations,  utility  factors,  security/ protection  measures,  etc.,  as  seen 
from  the  user  viewpoint.  If  graphics  are  used,  support  each  with  narrative 
explanations. 

4.2  Input,  Actions,  and  Output 

Describe  each  feature  of  the  program,  as  visible  or  of  interest  to  the  user, 
in  sufficient  detail  that  the  user  may  apply  the  procedures  for  use  contained 
in  Section  5,  Correspond  features  or  combinations  of  features  of  the 
program  to  applications  as  necessary,  and  describe  the  options  that  may  be 
excerised  in  each  case.  Cite  and  illustrate  the  advantages  to  be  gained 
through  use  of  these  features  in  appliGations.  (Input,  processing,  and  output 
characteristics  pertinent  to  usage  will  normally  be  integrated  together  in  a 
narrative  fashion,  feature  by  feature.  However,  the  outline  below  is 
segmented  into  three  separate  subsections  so  as  to  delineate  specific  items 
for  discussion.) 

4.2*1  Input  Characteristics 

Define  the  requirements  of  collecting  and  preparing  user  input  data, 
parameters,  and  controls.  Typical  considerations  are:  (l)  purpose  or 
conditions— -e.g.,  to  make  needed  revisions  to  data  base;  (2)  frequency— 
periodically,  randomly,  or  as  a function  of  an  operational  situation;  (3) 
origin-^network  operations,  program  office,  budget  data  base,  spacecraft 
sensor,  etc.;  (4)  accuracy  required  for  meaningfot  output;  (5)  medium- 
punched  card^  manual  keyboard,  magnetic  tape;  (6)  restrictions— amount  of 
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data,  priori^,  use  authomatidn,  security  limitations;  (T)  quality  eorttrol^ 
instructions  for  checking  reasonableness  of  input  data,  actions  to  be  taken 
when  data  appears  to  be  received  in  errors  documentation  of  errors,  etc.;  (8) 
disposition^instructions  for  retention,  release,  or  distribution  of  input  data 
received. 

4.2. 1>1  Input  Format 

Provide  the  layout  forms  and  syntax  as  necessaiy.  Include  a description  of 
each  entiy,  with  adequate  grammatical  rules  and  conventions  used  in  each 
case.  Distinguish  literal  input  from  syntactic  variable  identifiers.  Typical 
considerations  includet  {l)  lengthy  as  characters /line  or  eharacters/item;  (2) 
format,  as  for  example^  left-justified  free^form  with  spaces  between  items; 
(3)  labels,  tags,  or  identifiers;  (4)  sequence,  or  the  order  of  placement  of 
items  in  the  input;  (5)  punctuation,  or  use  of  spacing  and  symbols  to  denote 
start  and  end  of  input,  of  lines,  of  data  groups,  of  items,  etc.;  (6)  rules 
governing  the  use  of  groups  of  particular  characters  or  combinations  of 
parameters  in  an  input;  (7)  the  vQcabulaty  of  allowable  combinations  or 
codes  that  must  be  used  to  identify  or  compose  input  items;  (8)  units  and 
Gonversion  factors;  (9)  optional  elements  and  repeated  elements;  (lO) 
controls,  such  as  headers  or  trailers, 

4.24.2  Sample  Inputs 

Provide  specimens  of  each  type  of  complete  input  form,  Such  specimens 
should  include j as  applicable:  (l)  control  or  other  header  information 
denoting  class  or  type,  date  and  time  origin,  or  function  codes;  (2)  text  or 
other  input  data  to  be  processed  by  the  program;  (S)  trailer,  denoting  the 
end  of  input  and  other  control  data;  (4)  indication  of  omissions,  i;e,^  classes 
or  types  of  data  that  may  be  omitted,  or  are  optional;  (3)  indication  of 
repeated  data,  i.e,,  classes  or  types  of  data  that  may  he  repeated,  and  the 
extent  of  such  repetition. 

412.2  Processing  Characteristics 

Describe  the  processing  performed,  ineluding,  as  pertinent:  (l) 
transformations,  manipulations,  and  reductions  on  data;  (2)  accuracy  pr 
preGision  in  computations;  (3)  sequences  of  actions;  (4)  logical  eorteepts;  (5) 
error  checks  and  diagnostics;  (6)  provisions  for  recoveiy;  (7)  controls  and 
options;  ('8}  applications  restricUonSi 

4.2.3  Output  Characteristics 

Describe  each  of  the  output  forms  or  other  program  responses  to  the 
user  in  sufiicient  detail  for  his  effective  interpretation  in  stated  applications. 
Typical  considerations  include:  (l)  use— by  whom  and  for  what  purposes; 
(2)  frequency— weekly,  periodically,  or  on  demand;  (3)  variations— 
modifications  that  may  appear  on  the  basic  output;  (4)  destination— which 
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users  or  work  area;  (S)  medium-printout,  punched  cards,  GRT  display;  (6) 
qual%  control— instructions  for  identification^  checks  for  reasonableness, 
authorization  to  edit  or  correct  errors;  (7)  disposition— instruetions  for 
retention  or  release^  distribution,  transmission,  priority,  security  handling, 
and  privacy  considerations. 

4,2.3^!  Output  Formats 

Provide  a layout  of  each  user’^pertinertt  output,  with  explanatoiy  material 
keyed  to  the  particular  parts  of  the  “format  illustrate.  Include  (l)  header- 
title.  identification,  date,  number  of  output  parts,  etc.;  (2)  body- 
information  that  appears  in  the  body  or  text  of  the  output,  columnar 
headings  in  tabular  displays^  and  record  layouts  in  machine  readable 
outputs,  noting  which  items  may  be  omitted  or  repeated;  (3)  units  and 
conversion  factors  for  numeric  fields;  (4)  legends  for  abbreviated  data;  (5) 
acciiracy;  (6)  trailer— summaiy  totals,  end-rof-output  labels,  etc. 

4«2.3,2  Sarnple  Outputs 

Provide  illustrative  examples  of  each  type  of  output  In  each  ease  discuss 
(l)  the  meaning  and  use  of  control  data  applied;  (2)  the  source  and 
Gharacteristics  of  the  data  processed;  (3!)  pertinent  facts  about  the 
calculations  made  by  the  software;  (4)  cbaraeteristics,  such  as  the  presence 
or  absense  of  items  under  certain  other  conditions  of  the  output  gEheration, 
other  ranges  of  input  values,  or  different  units  of  measure, 

4.3  Use  of  the  Program 

Explain  how  the  program  and  its  features  are  to  be  applied  over  its 
spectrum  of  applications.  Give  selection  criteria  and  specific,  graphic 
examples  that  match  the  program  inputs,  actions,  and  outputs  to  their 
intended  interpretations.  Describe  any  human  post-processing  of  the 
presented  output  which  may  be  required  for  eflFeetive  use  of  the  program. 
State  what  inferences  one  may  draw  from  output  data,  if  any. 

The  intent  of  this  infomation  is  to  give  the  reader  sufficient  insight  to 
judge  whether  the  program  applies  to  a particular  problem;  if  it  does,  then 
this  information  should  tell  how  to  make  the  data  into  and  out  of  the 
program  correspond  with  the  parameters  and  facts  concerning  his 
application, 

4.4  Performance  Gharacteristics 

Describe  the  performance  charaGteristics  of  interest  to  the  user, 
including,  where  appropriate:  (l)  quantity  of  input  aud  output;  (2) 
throughput  rate;  (3)  accuracy;  (4)  cost  of  service;  (S)  turn-around,  time;  (6) 
reliability;  (7)  flexibility;  fs)  quality  of  service. 
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4.5  Security  and  Privacy 

Describe  security  and  privacy  measures  implemented  in  the  program  that 
restrict  its  usage  or  guard  data  integrity  via  authorization  keys,  priorities, 
protocols,  etc.  Instruct  the  user  what  features  are  operative  within  the 
several  authorization  levels,  and  identify  penalties  for  inadvertent  or 
malicious  misuse.  Provide  warning  and  cautionaiy  information,  if 
applicable. 


5.  PROCEDURES  FOR  USE 

This  section  describes  how  to  prepare  data  or  instructions  to  operations 
in  order  to  apply  the  program  to  problems  it  can  handle,  or  to  achieve  a 
desired  processing  and  output.  The  material  delineating  input,  run,  output, 
and  other  procedures  below  can  be  integrated  together  to  enhance 
readabilify,  if  appropriate,  and,  perhaps,  integrated  with  the  material  of 
Section  4 as  well,  to  match  the  feature  descriptions  with  the  procedures  for 
their  use. 


5.1  liiitiatibn  and  Protocols 

Describe  the  user/ operations  protocols  necessary  to  initiate  a niOj  submit 
input,  and  receive  output  Discuss,  as  appiropriate:  (l)  opening  a computer 
work  order;  (2)  assignment  and  use  of  passwords  and  account  codes;  (S) 
authorization  to  use  system  and/or  data  base  files;  (4)  assignment  of 
permanent  private  files;  (s)  instructions  for  pickup  or  delivery  of  I/O 
material  and  running  the  program;  (fi)  difierences  between  interactive  and 
batch  protocols;  etc. 

5.2  Preparation  of  Input 

Describe  the  procedures  for  gathering  input  data  and  putting  it  in  the 
fpnnat  required  for  ninning  the  prograniv  Such  procedures  might  include: 
(l)  the  method  of  extracting  data  from  source  documents  or  files;  (2)  usage 
of  data  preparation  and  editing  aids  or  other  software;  (3)  usage  of  special 
services,  such  as  keypunch  operators;  (4)  a checklist  to  determine  rapidly  if 
everything  h^  been  done;  (5)  special  considerations  for  alternative  input 
media;  (6)  special  considerations  for  batch  ys,  interactive  operation;  etc. 

5.3  Run  Procedures 

If  processing  requires  or  permits  interaction  or  monitoring  by  the  user, 
provide  instructions  for  terminal  operations;  Describe  (l)  terminal  setup  or 
connect  procedures,  e.g.,  log-on;  (2)  loading  and  start  up  procedures;  (3) 
data  or  parameter  input  procedures;  (4)  control  instructions;  (S)  magnetic 
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tape  operational  procedures;  fS)  cassette  tape  device  operation;  (7)  run 
interruption/rccovery;  (8)  run  abortion;  (9)  special  terminal  devices^  eg., 
plotters;  (10)  indications  of  anomalous  behavior  and  corrective  actions;  (ll) 
start,  restart,  and  other  precautions;  etc, 

5.4  Output  Handling 

Describe  applicable  policies  and/or  procedures  within  the  user 
environment  for  handling,  disposing,  dissemination,  and  routing  of  the 
various  forms  of  output;  for  storage  or  archiving  of  output  items  for  their 
later  retrieval;  for  status  reporting  based  on  output  parameters;  for 
extraction  and  summarizing  of  information;  for  audits  or  other  inspections 
of  the  output  data,  deadlines,  etc, 

5.5  Restrictions  on  Use 

Identify  and  explain  exceptions  and  restrictions  in  the  procedures  for 
preparing  input,  using  the  program^  or  handling  the  output.  Such,  material 
might  address  (l)  limited  availability  of  source  data;  (2)  security 
considerations;  (3)  processing  cost  vs,  tiihe  of  day  limitations;  (4) 
restrictions  on  amount  of  input  or  output;  (5)  accuracy;  etc.  The 
restrictions  and  exeeptiGns  discussed  here  are  restrietions  in  usage 
procedures^  rather  than  in  the  program  applications. 

5.6  Eiror  Handling  and  Recovery  Procedures 

If  not  adequately  covered  in  other  parts  of  the  manual,  describe  (l) 
detection  procedures  for  anomalom  output  data;  (2)  meanings  of  error 
messages,  codes,  or  indicators;  (3)  prescribed  corrective  actions  by  the  user; 
(4)  proeedures  for  correcting  input  errors,  for  restart/ recovery,  for 
reporting  of  anomalous  behavior,  etc. 


a THEORY  OF  APPUCATIQNS 

In  some  cases  a short  section  revealing  salient  aspects  of  the  program 
model  is  an  advantage  in  being  able  to  use  the  program.  In  such  eases, 
describe  in  this  section  the  theory  required  for  effective  use  of  the  program, 

6.1  The  Progrem  Model 

If  the  program  reflects  a real-world  situation  implemented  via  a 
parameterized  software  model,  describe  the  model,  the  assumptions 
necessary  for  model  validity,  the  correspondence  between  program 
parameters  and  real-world  values,  the  pertinent  differences  between  the 
model  and  actuality,  and  comparisons  with  other  models  or  programs. 
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6.2  Algoilthm  Analysis 

If  the  actual  programmed  procedure  or  sequence  of  steps  executed  hy  the 
program  influences  effective  application  of  the  program,  discuss  the 
pertinent  details  of  the  algorithms  involved.  Such  an  analysis  might  address 
program/user  interaction  and  sequence  of  operations  for  the  various 
operating  modes,  aGcuraey  of  steps,  non-convergence  in  unusual  cases, 
circumstances  under  which  the  program  runs  inefficiently  or  requires  large 
allocations  of  storage,  circumstance  under  which  processing  is  veiy 
efficient,  etc 

6.3  Extensions  and  Ufnitations 

If  the  program  model  or  algorithms  have  sufficient  generality  for  later 
extension  to  wider  applications,  or  for  modiflcation  to  new  application 
areas,  and  these  qualities  influence  the  way  the  program  is  used  or  chosen 
for  an  application,  they  can  be  described  in  this  section.  If  there  are 
limitations  in  the  model  or  program  algorithm  that  limit  the  applicability 
of  the  program,  and  which  may,  perhaps,  cause  the  user  to  analyze  the 
particular  circumstances  of  his  application  as  a result,  then  these 
restrictions  can  be  similarly  discussed. 


7.  APPENDICES 

Appended  material  may  include,  but  are  not  limited  to,  explanatory 
material  and  references  of  an  auxiliary  nature,  inserted  directly  or  bound 
separately  for  convenience.  The  following  suggested  topics  are  typical. 
Appendices  may  be  designate  as  " Appendix  A,’"  etc^,  if  desired,  rather  than 
by  the  Dewey-decimal  system  given  here, 

7.1  Gloseary 

Give  a list  of  mnemonics,  acronyms,  and  unfamiliar  or  specially  used 
terms  appearing  in  the  manual;  provide  definitions  for  each. 

7.2  References 

Provide  a bibliography  of  references  to  other  documents  appearing  in 
this  manual.  For  each,  include  a brief  statement  indicating  the  nature  of  the 
subject  matter  and  purpose  of  the  reference. 

7.3  Input  and  Output  Formats 

Provide  detailed  formats  and  syntax  for  data  inputs  and  outputs,  together 
with  associated  responsets)  as  supplementaiy  material  to  Section  4,2. 
Define,  as  appropriate;  (l)  data  base  I/O  formats,  parameters,  and  control 
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characteristiGS;  (2)  Gommunicatidns  device  I/O  i^ormats,  parameters,  and 
control  characteristics;  etc. 

7.4  Auxiliary  Tabtes 

Assemblie  in  tabular  form  auxiliary  reference  material  needed  for 
program  usage  that  is  better  located  in  an  appendix  rather  than  in  the  text 
proper*  Display  each  table  in  a separate  subsection,  7*5*i,  and  introduce  dr 
explain  the  use  of  each  table  narratively* 

7.5  Summary  of  Features 

Providte  an  abbreviated  description  of  each  of  the  program  features  for 
the  knowledgeable  user,  This  summary  should  be  devoid  of  tutorial 
explanations,  containing,  instead,  only  technical  descriptions  or  definitive 
examples  for  quick  reference* 

7.6  Detailed  Examples 

Display  the  usage  of  the  program  via  sample  runs  from  beginning  to  end; 
Show  all:  input,  indicate  all  inteFactidns  in  timely  sequence,  and  display  all 
output  Give  examples  of  normal  and  abnormal  runs,  and  illustrate  the 
procedures  followed  in  each  case. 


APPENDIX  6 

i 

CRISP  SYNTAX  AND  STRUCTURES 

[ 

i 

i 

chapter  7 introduced  a family  of  languages  based  on  a common  set  of 
i Gontrol  structures  called  CRISP.  The  principal  use  of  CRISP  in  this  text  has 

been  to  illustrate  the  isomorphism  between  CRISP  structures  and  flowchart 
topologies,  the  use  of  a procedural  design  and  description  language  that  is 
riot  keyed  to  a specific  coding  language,  and  the  natural  conversion  of  these 
: program  descriptions  into,  perhaps,  unstructured  coding  languages. 

i 

This  appendix  contains  a fimctidnal  description  for  three  types  of  CRISP 
f processors:  CRISP-PDL,  the  design  and  documentation  aid;  CHISPFLOW, 

i a graphic  aid  that  flowcharts  program  algorithms;  and  CRISP  translators, 

I which  overlay  such  unstructured  coding  languages  as  FORTRAN  or 

assembly  language  and  promote  the  one-tG-rOrie  correspondence  between 
design  and  code  via  commonality  of  syntax  and  form. 

1 have  chosen  to  pattern  this  description  in  the  form  of  a Software 
Functional  Specification,  using  Appendix  E as  a guide  for  topical  material. 

; Front  matter  and  such  sections  that  are  non-appHcable  have  been  omitted. 

To  limit  space,  all  of  the  Programming  Specifications  and  Test 
SpecifiGatipns  normally  found  in  an  SSD  have  been  eliminated  from  this 
appendix.  Even  the  functional  specifications  that  do  appear  admittedly  lack 
concreteness  and  detail  in  certain  particulars. 

This  appendix,  as  it  stands,  then,  should  be  viewed  as  preliminaiy  and 
embryonic  in  the  development  of  a CRISP  system.  Neverthless,  the  format, 
content,  and  level  of  the  document  are  probably  sufiRcient  for  the  purpose 
of  this  text,  both  to  define  most  of  CRISP  and  to  illustrate  what  an  SSD 
might  typically  look  like  during  the  software  development  process.  Other 
examples  of  SSDs  appear  in  Appendix  L. 
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CRISP 

SOFTWARE  SPECIFICATION 
DOCUMENT 


t iNTRODUGTION 

1.1  Purpose  of  this  Specification 

CRISP  is  a set  of  Control  Restrietive  /nstnictions  for  Structured 
ftogramming.  It  consists  of  a few  forms  that  conform  program  control  flow 
into  structured  designs.  Programmers  using  a CRISP  system  document  their 
designs  and  write  code  using  the  most  appropriate  languages  available, 
except  for  statements  governing  program  control  flow.  CRISP  statements 
are  used  in  lieu  of  the  control  statements  of  the  language  being  used. 

CRISPFLGW  is  a form  of  CRISP  that  turns  CRISP  documentation  into 
structured  flowcharts.  CRISP-PDL  is  a program  design  and  documentation 
tool  that  allows  all  but  CRISP  ^tax  to  be  freely  chosen  (usually 
abbreviated  Englishj),  and  h^  as  its  output  cosmetized  indented  listings, 
identifier  cross-references,  a tier  chart,  a glossary,  a table  of  contents,  stub 
status  reports,  and  a statistical  usage  summary.  Other  CRISP  processors 
govented  by  this  specification  translate  input  statements  into  an  arbitrary 
given  target  language,  With  execution  monitors  inserted  automatically  when 
desired  for  correctness  testing. 

This  specification  sets  forth  the  syntax  and  semantics  of  the  CRISP  forms; 
it  is  the  controlling  standard  for  all  processors  implemented  in  the  CRISP 
family. 

1.2  Scope  of  Applicability 

This  doGumerit  sp^ifies  functionally  that  part  of  CRISP  which  covers  the 
basic  control  structures  (sequence,  alternative  selection,  looping,  and 
procedure  linkages)  and  miscellaneous  features  such  as  macros,  line 
continuation,  paranormal  exits,  comments,  and  end  of  processing.  This 
specification  does  not  cover  nor  preclude  possible  subsets^  supersets,  or 
other  options  that  may  be  implemented  into  a specific  processor.  However, 
all  processors  using  the  CRISP  title  must  use  features  strictly  in 
conformance  with  the  minimum  standards  herein  contained.  The  CRISP 
foniis  described  here  are  impleinentation  independent;  neither  syntax  nor 
semantic  value  may  be  altered  to  benefit  a specific  processor  design. 

Section  2 of  this  specification  contains  standards  and  conventions  ased  in 
this  SSD,  Section  3 discusses  environmental  and  interface  assumptions. 
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Section  4 forms  the  main  body  of  functional  specifications  for  CRISP. 
Sections  5 and  6 have  been  omitted  as  being  implementation  oriented,  and 
Section  7 contains  appended  material  relative  to  the  functional  behavior  of 
CRISP  only. 

1.3  System/Subsyet^m  Overview 

Inasmuch  as  the  features  described  in  this  document  are  meant  to  be 
machine  and  software-system  independent,  the  programming  and  opera- 
tional environment  for  CRISP  are  assumed  to  conform  to  a broad,  generally 
nbn-restrictive  set  of  standards.  The  assumpf ions  that  appear  explicitly  and 
iniplicitly  herein  have  been  made  chiefiy  to  foster  the  readability  of  this 
document  rather  than  to  set  system  requirements  for  an  implementation. 
Environmental  character  is  ties  substantially  diflFering  from  assumptions 
herein  stated  are  permitted  to  govern  so  long  as  they  do  not  lead  to 
conflicts  with  syntactic  and  semantic  specifications  set  forth  in  this 
document,  nor  produce  viewable  outputs  with  significant  variations  from 
those  formats  specified.  Further  details  appear  in  Section  3. 

1.4  General  Description  of  CRISP 

The  quality  of  a computer  program  can  often  be  significantly  influenced 
by  the  design  medium  in  which  that  program  is  developed,  embryonically 
and  evolutionarily,  from  the  ideas  that  permeate  the  programmer  s mind  to 
the  completed  programming  speeification.  The  medium  must  foster  the 
expression  of  such  ideas  easily  and  quickly  (sometimes  before  they  fade 
from  memory),  and  must  permit  flexible  and  facile  alterations,  additions, 
and  deletions  to  these  ideas  as  the  design  evolves.  Moreover,  the  expression 
of  the  design  should  be  as  graphic  as  a “picture  of  the  program”— yet  not 
be  the  program,  nor  constrained  by  the  syntax  of  a computer  langitagC;  At 
the  final  evolutionary  stage,  such  descriptions  should  form  the  principal 
program  design  documentation. 

A '‘program  design  language”  or  “procedural  description  language”  is  a 
formalized  embodiment  of  such  design  aids,  and  can  take  many  forms. 
Probably  the  most  familiar  form  is  flowcharting.  This  specification 
describes  a procedure-oriented  language  type  and  processors  for  it,  which 
result  in  program  specifications  and  code  that  can  appear  much  like 
flowcharts.  Moreover,  if  proper  attention  has  been  paid  to  certain 
limitations,  the  GRISP  statements  can  be  flowcharted  directly,  using 
CRISPFLQW  as  described  in  Section  4.2.2. 

A program  design  in  CRTSP^FDL  consists  of  short,  English  textual 
descriptions  of  data  manipulations,  operations,  and  functions  imbedded 
within  stnictured  CRISP  controMogic  syntax,  The  output  listing  of  CRISP- 
PDL  displays  the  program  as  modules  of  hierarchically  refined  algorithms 
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cosmetically  formatted  into  2>dimensional»  flowchaitdike  segments.  There 
is  no  restriction  on  the  use  of  the  English  textual  materia^  only  on  the 
usages  of  the  program  control  logic,  that  must  adhere  to  certain  syntactic 
rules  (to  be  further  described  later  in  this  document). 

CRISP  translators  access  sequential  source  records  and  replace 
recognized  control-logic  statements  by  equivalent  target  language  code  that 
performs  the  specified  control  flow.  Although  the  programming  specifica- 
tion is  not  part  of  this  document,  it  may  be  useful  for  the  reader  to  envision 
this  translation  process  in  the  form  of  macros  invoked  by  the  CRISP 
statements;  each  target  language  has.  its  own  set  of  '"plug  in”  macro  bodies 
specifically  tailored  to  that  language.  Descriptions  of  the  STACE-2  general 
puqiose  macro  processor  (References  7.2.1  and  7.2.2)  contain  enlightening 
information  regarding  the  use  of  such  replaceable  macro  forms  in  portable 
programming  applications.  Alternatively,  CRISP  may  form  the  control 
sublanguage  of  a fully  compiled  language. 

CRISP  preempts  all  control  statements  from  a base  language  and 
substitutes  forms  that  force  programs  to  be  structured  in  control.  However, 
this  specification  does  not  require  that  CRISP-preprocessors  analyze  non- 
CRISP  statements  syntactically;  hence,  usage  of  non-CRISP  control  forms 
are  not  prohibited  by  this  specification  (but  neither  are  they  encouraged). 

Programmers  may  thus  construct  code  using  statements  from  a 
background,  or  base  language,  such  as,  perhaps,  FORTRAN  or  Assembly 
Language,  except  for  statements  that  govern  the  flow  of  control  (branching, 
looping,  etc.).  Such  control  is  accomplished  by  the  use  of  statements  as 
specified  in  this  document. 

The  source  program  thus  consists  of  a mixture  of  CRISP  control- 
structure  statements  and  base-language  code,  A preprocessor  for  such  a 
source  program  would  then  translate  or  otherwise  process  only  those 
^ CRISP  constructs  back  into  the  equivalent  base-ianguage-coded  stnictures 
for  compilation.  Base-language  statements  would  be  passed  to  the  compiler 
directly  (possibly  with  some  format  adjustment). 

All  functions  herein  described  make  no  assumptions  relative  to  whether 
the  CRISP  processors  are  real-time,  interactive,  or  batch  operated.  The 
processors  are  assumed,  however,  to  be  solely  data  manipulative,  with 
reasonable  restrictions  on  throughput  rate  and  efficiency,  and  arc  not 
restricted  to  single-pass  translation. 

Translators  may  be  preprocessors  for  a given  base  language,  such  as 
FORTRAN,  BASIC,  or  Assembly  Language,  or  may  be  full  compilers  for 
languages  with  CRISP  as  the  control  sublanguage^ 
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2.  STANDARDS  AMD  GONVENTIONS 

This  section  describes  standards  and  conventions  used  in  this  SSD  to 
describe  the  external  characteristics  of  GRISP. 


2.1  Si^lffcatlon  SUmdards  and  Conventions 

Flowcharts  drawn  by  CRISPFLOW  and  illustrated  in  this  SSD  adhere  to 
ANSI  standards  (Reference  7.2.3)  a*^  augihented  or  intei^reted  to  fill  the 
needs  of  structured  programming,  as  put  forth  in  Reference  7.2.4.  As  a 
further  convention,  binaiy  decision  boxes  on  flowcharts  show  the  true 
fiowline  leaving  on  the  left, /o/se  on  the  right.  Multiple-decision  symbols 
have  the  results  displayed  in  case-order  from  the  left.  These  conventions 
liiake  top-down4eft-to-nght  flowchart  scanning  correspond  to  top-down 
readabiiity  of  the  CRISP  code  structures. 

Italicized  lower-case  identifiers  in  Section  4 of  this  document  identify 
syntactie  variables,  for  which  a substitution  must  be  made;  Subscripts  may 
appear  on  syntactie  variables  to  distinguish  multiple  usages  of  the  same 
type.  Square  brackets,  [ ],  enclojse  optional  fields.  The  syntactic  variable 
fypes  are  listed  below: 

comment:  rtring  of  characters  not  containing 

date:  string,  presumed  to  be  date 

dewey:  decimalized  module  identification  iiUinber 

event:  interrupt  label 

eventUst:  list  of  events 

expression:  target  syntax  numeric  expression 

fname:  function  name,  target  syntax 

identifier,  alphanumeric,  possibly  with  periods  and  underscores 
index:  target  syntax  discretewalued  variable 
integer:  positive  integer,  no  decimal  pomt  or  sign 
ABORT  transfer  point 
moduleehder:  keyword  ending  a module 
moduleheader  keyword  and  name  beginning  a module 
no w:  procedure  name,  arbitraiy  string 
pno/ne:  program  name,  perhaps  in  target  syntax 
predicate:  boolean-valued  expression  in  target  s>Tttax 
statement:  CRISP  or  base-language  statement 
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sNtig:  arbitraiy  stHng  of 

body  of  CRISP  wd  b£(is^lwguage^$^^ 
stibnam^:  subroutine  name,  target  ^ 
macrb  name/^iing  wlth^ 

. vaiuet  vsilne  of  index  or  OiiTCOME  variables 

xstibrinme:  external  subroutine  name^  target  syntax 

Procedural  speciSGatibn  standards  are  to  be  supplied  prior  to 
commencement  of  the  design  actiyi^^ 

2.2  Programmijtig  ^ 

Programming  staitdaids  are  not  addressed  by  this  specification.  To  be 
supplied  pnbr  to  commencemeiU:  of  coding, 

24  Test  and  VbriRit^ 

Test  and  verification  standards  are  not;  covered  by  this  speciflcatiOii.  To 
be  supplied  prior  to  commencement  of 

24  Ouaitty  Assurance 

QA  standmds  are  not  covered  by  this  specificatipn.  To  be  suppli^  pripr 
to  commencement  of  codings 

3.  ENVlRONMEMT  and  11^ 

3^1  System/Subsystem  Descriptidn 

As  discussed  eariier  (Secri^  1:3).  these  CRISP  specifications  are  very 
general  with  respect  to  the  q^em  environmerit.  There  are,  thus,  no 
applicable  system /subsystem  documents.  Interfaces  between  the  CRISP 
user  and  operations  are  also  undefined  by  this  specificatipn.  The  user  is, 
therefore,  assumed  to  be  responsible  for  the  generation  and  prep^ation  of 
source  materials  and  for  the  following  of  standard  procedures  and  protocols 
Operative  within  the  computation  facili^  hosting  the  CRISP  system. 

Even  though  this  CRISP  specificatio  shielded  from  the  operating 
system  and  hardware,  certain  assumptions  about  input,  output^  aind  storage 
media  are  necessaiy.  The  characteristics  of  these  media  and  the  constraints 
they  impose  on  the  program  are  discussed  in  Section  3.2,  below.  Interfaces 
with  suppoiting  programs  are  discussed  in  S 

3^  Hai^waiB  CharactOrisUcs  and 

The  hardware  functional  Gharacteristics,  displayed  gFaphicaliy  in  Figure 
include: 
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• A progr^  core  aito 

• A control-input  medium  (optional  in 

• A scratch-file  capability 

• A diagnostic  output  di^ 

• An  output  listing  device  or  displa^^ 

• Target  code  output  medium  (for  GRISP  translators) 

• Sufficient  membiy  for  tables  and  lists 

• Plotting  capability 

Constraints  imposed  on  the  hardware  by  this  speciliGation  are  (l)  that 
these  media  be  available  in  a form  judged  to  be  suitable  for  the  particular 
iiiipiementation;  (2)  that  the  ainount  of  storage  needed  for  such  things  as 
cross-referencing  of  identifiers,  tier  charts  table  of  contents,  glossary,  mac/o 
translation,  etCi,  be  sufficient  that  programs  of  signifiGahi  size  be 
acGommodated;  Information  relative  to  these  limitations  may  be  deter- 
mined Separately  for  each  iniplementati 

For  the  purposes  of  yi^aliring  CRISP  spepificatrons^  the  reader  may  find 
it  useful  to  envision  these  media  assign^  as  follows:  The  source  input 
comes  from  disk  files  named  by  the  contrdl-data  input  device,  aii 
interactive  demand  terminal,  from  which  the  other  program  options  can 
also  bt'  Input.  The  program  scratch  files  are  disk  files,  and  the  output 
medium  is  the  ^tem  line  printer.  Diagnostics  and  monitor  data  appear  at 
the  user  terminal  The  CRISPFLOW  plotter  draws  straight  lines  between 
points  specified,  and  lines  may  be  output  in  random  order.  The  operating 
mode  is  either  online  or  batch,  demand  or  queued;,  and  operates  as  a 
sequential  prograniv 

3.3  Software  EnvIrbnmeM^ 

The  software  required  for  CRISP  consists  of  an  unspecified  language 
compiler  or  compitei^  suitable  to  implement  and  maintain  the  source 
processing  tasks  described  in  Section  4 and  to  manipulate  properly  the 
media  in  S^tion  i2i  ^boye.  In  addition,  text  editing  and  debug  facilities 
are  required  for  program  developments  using  CRISP.  No  standards  are 
hereby  set  by  this  document  for  these  tools. 

3j4  Interfiice  Characteristics 

Interface  characteristics  between  CRISP  processors  and  the  system  shaU 
be  defined  by  standardis  and  protocols  imposed  by  or  negotiated  with  the 
operating  enviroiunent  GRISP  source  media,  however,  shall  be  compatible 
as  follows:  All  CRISP  source  data  sh^  be  accessible  by  CRlSP-Pl>L  arid 
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CRISPFLOW  for  proc^lrigi  Hiat  is,  all  source  data  can  be  proceed 
GRISP-PDL  for  indehtihg,  cross^refetencittg;  etc.,  aiid  flowcharts  can  be 
generated  from  all  forms  of  source  input,  as  well  (provide  care  is  taken  to 
assure  that  the  amount  of  tejct  and  numbers  of  boxes  do  not  yield  flowcharts 


4 QRISP  FUNGTIdNAL  SpEGI^ 

4.1  Funttidnal  OrganizaUbn  arid  dverview 

The  discussion  of  the  CRISP  system  Will  apply  to  CiRlSPrPDL, 
CRISPFLQW,  and  CRISP  translators.  The  syntax  of  statements  for  each  is 
the  same/but  the  output  varies  according  to  the  particular  processor  used. 
The  CRISP  ^itor  is  not  covered  by  this  specification. 

Except  for  comments,  CRISP  constructions  are  keyword  actuated.  That 
is,  the  first  symbol  or  symbols  oh  each  line  uniquely  identify  whether  a 
source  statement  is  a CRISP  form  or  belongs  to  the  base  language^  Such 
keywords  identify  the  beginnings  of  structures  and  substructures,  linkages  to 
other  structures,  or  the  end  of  stiuctures  or  substructures. 

Because  the  CRISP  statements  'j*e  keyword  actuated,  it  is  necessary  that 
stathmehts  in  the  base  language  not  begin  with  these  keywords.  CRISP 
structures  can  conceptually  be  iterated  and  nested  tp  any  desired  level  to 
produce  the  intended  progran^.  However,  flowcharting  or  the  use  of 
indentation  to  identify  levels  of  nesting  and  to  promote  readability  tends  to 
limit  how  many  levels  can  actually  be  acconiinodated  as  a practical  matten 
Thfy  specification  does  not  limit  the  maximum  number  of  levels.  The 
miiiimum  number  of  levels  that  CRISP-PDL  and  CRISPFLOW  can 
accommodate  must  be  no  less  than  10. 

In  arriving  at  the  structures  and  syntax  herein  contained,  a number  of 
concerns  have  been  expressed  and  evaluated  relative  to  alternatives  within 
the  purview  of  this  specification.  Some  of  the  criteria  that  shaped  this 
specifiGation  are  lirted  below. 

These  criteria  led  to  the  selection  of  imperative-farm  verbs  for  naming 
actions  to  be  taken,  possibly  modified  by  conjunctives  (if,  UNLESS,  WHILE, 
until).  Alternative-selection  stiiictures  are  introduced  by  predicate^ 
conjunctives  (iFi  in  case).  Almost  all  structures  that  iritroduce  a level  of 
nesting  of  statements  within  that  structure  conclude  with  an  appropriate 
ENDii^  where  rex  identtfies  the  of  structure  being  closed,  (An  error 
message  will  occur  when  a mismatch  occurs  between  the  structure  in  eflect 
and  the  Ei^^ 
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At  one  poiht  during  the  generafidh  of  this  specificaftoh,  ^ere  was  a 
concern  whether  CfUSP  staternenl^  should  ignpi^e  blfOilcs  inputs- 

as  does  RMflPRANMor  whether^  C^  hy 

i^idring  spaces^:ih  as  striitg  delimiters.  The  ^al  deGision 

was  that  CRI^P  shall  specify  the  use  of  ^aces  to  deh  s}mtact!c  elements 
only  in  those  places  required  by  a preprocessor  to  discern  kig/rwO 


The  list  below  its  an  ordered  set  of  concerns  Uiat  were  the 

fbr^  of  this  specificatipn.  The  order  shown  displays  the  approximate 
iptiprity  pf  that  con 

1,  Minimum  number  of  control  structures  consistent  with  programming 
effibieiiGy. 

2,  Generality  of  appite 

3*  Clarity,  readability,  uriderstandabillty  of  ^ 

4.  E^e  in  assessmeht  of  program 
5*  Implications  of  autom^ 

6.  Consistent  fpnn  of  ^ta^ic  elem^^ 

7,  Impleinentation  ease  (single  vs;  multiple'^pass  processing). 

8*  Ease  of  use,  interactive  and  b 

9.  Blahk^hdependence  of  syntax. 

4.LldveiriewpfC^ 


The  GRiSP-PDL  processor  is  principally  a text-rfonnatting,  annotation, 
and  crosS-reference  generating  device  (Figure  4.1. i.l).  A procedure  input 
line  consists  of  possibly  three  fields:  a prefix,  a Gosmetic,  and  the  text.  The 
prefix  contains  possibly  a step  number  within  the  module  (usually  chosen  to 
correspond  to  a box  pn  a flowchart)  and  any  subroutine  or  function 
floweh^  cross-references;  The  cosmetic  portion  consists  df  spaces  and 
vestig^l  flowlines^  so  as  to  present  an  indented  listing,  which  then  also 
displays  m^y  cf  the  featured  of  a flowchart. 

In  procedural  di^ciipti  the  text  field  of  the  input  is  of  two  varieties: 
either  a conjtrbl-lpgic  text,  or  else  a " ■base-language”  (rion-control-logic) 
text.  The  text  field  is  distinguished  as  the  field  beginning  with  the  first  non- 
cosnaetic  character  following  the  first  space  encountered  on  a tine.  Controb 
Ipgie  text  fields  begin  w:ifh^^  a siich  as  IF^  LOOP,  REPEAT,  or  a left 

parentherisvVt'V 

Keywords  signal  the  processor  to  increase  or  decrease  the  indenting  level 
and  to  add,  delete,  or  modify  the  vestigial  flowlines*  Tbe  head  of  nested 
stnt<^ures  (e,g,,  IF,  LOOP,  ELSE,  etc.)  increase  the  indenting  level  and  add 
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Control  data  to  all  preceding  functions 


Figurn  Functional  data  flow  In  tlie'GRlSP-PDL  processor 
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flitmltos;  endings  of  nest^  ^tniciiiiriK  (eg;,  pioiF,  enoc^e%  ete) 

deci#8i$e  tbe  ihdimtiifg.  levd  and  ei^fcare  dowlines.  Abnormal  and 
pmtmorrod  exits  (EkXTi  return,  stop,  and  sysTEM)  cause  no  change  in 
ii^dentihg  lievuk  but  dO  show  a flowline  (»it  of  tbe  current  nestiAg  level 
back  to  the  ajiprafpi^te 

Since  CBdSP-rPDL  responds  Only  to  k^nyofds,  control  structures  of  the^ 
base  laii^age  will  not  produce  extra  levels  of  iiidentatioa  or  cosinetic 
Sbwlines. 

CSISP-PDL  also  has  features  for  cross-refereiictog  procOduire  and  data 
itaines,  gesierafion  of  a table  of  contents  and  tier  charb  a cOmpietion  status 
report,  and  k^nvoidu^ge  sununaiy 

4 j.2  Overview  of  C^USpm 

CR^PFLOW  sweeps  €RISP>PPL  andOtherGRISP  processo  | 

processing  as  contTol*logic  structures  and  as  arbitrmy  text  strings,  from 
which  it  then  generates  flowcharts  (Figure  4. 1,2.1).  The  CRISP  logic  i 

stoictorm  determine  the  flowchart  topology,  and  the  text  stoings  label  the 
chart  appropriately.  Comments  (Section  4, 3, 3,  Imlbw)  are  not  ignored  in 
some  Statements  (e,g.,  oo,  call,  callx)  but  are  transferred  into  flowchart 
Itoxes  or  other  chart  annotations  direedy,  Some  comment  fields,  however, 
are  discarded,  as  detailed  in  Section  4.2.2,  be)ow> 


Since  CRISPFLOW  responds  only  to  keywords  in  plotting  control  flow, 
use  of  base  language  control  statements  will  not  be  detected,  and, 
tlmrefoire,  will  not  be  flowcharted  properly, 
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Flitwcbarts  are  drawn  tp  ANSI  standards  and  as  ptherw'ise  stated  in 
Secti^M* 


4;lr3  0yefvieiv  of  CRISP  Tiansto 

The  philosppihy  fpr  CRISP  translators  (Figuie  4.1^34)  presiimas  that  all 
pommenfs,  as  detailed  In  Seetion  444,  belbw,  will  first  be  removed  from 
the  source  cede,  that  the  fonnat  of  all  CRISP  constructs  wfit  then  be 
checked  for  syntactic  correctne^  and  that,  as  a miniiniim  rei|uirement, 
basedanguage  statements  and  strings  within  CRISP  statements  will  be 
transferred  into  direct  target  oUtpirt  without  further  ^tactic  analysis  and 
without  translation.  Compilers  based  on  CRISP,  however,  will  perform  full 
syntax  checking  and  translation  for  all  statements. 

4.1.4  Detectipn  of  and  Recovery  From  Systein  Failure 

Systein  failure  detection  and  recovery measures  during  CRISP  operations 
am  not  covered  by  this  Specification. 

4.1.5  Detection  of  and  Response  to  Source  Input  Errors 


As  a minimum  requirement,  all  CRISP  translators  shall  detect  errors  of 
the  fonGwing  iypes.v  (l)  missing  e CRISP  statements,  (2)  improper 


nguie  4,14^1.  the  cnfiP  translator  generates  tarsat  code,  while  CRISP'^POL  is  used  for 
lUMh^  (see  alae  Ngwa  m Reterenee  7iS.5) 


i 


9^  Apprise  G 

eteiiiehts  in  CIUSP  statements  after  a valid  kej^oi^  and  (3)  improper 
nesting  of  GRISP  struetiires  within  a procedure  imlt  SpeciiicaUy,  no  check 
Is  mandatpiy^  as  a requiremient  of  this  specification^  to  ascertain  whether 
base^Iangi^ge  contiold^  mechanisms  have  be^  employed;  rather  than 
those  specified  here*  CRiSP-P0L  detects  only  errors  of  tme  (3),  above,  and 
GRIS^LOW  detects  sonm  errors  of  ^es  (l)  and  (S)  as  itecess^  to 
deteimiim  flowchart  st^^ 

Upon  encouhteHng  su'i^h  errors  as  alluded  to  above^  the  processor  shall 
emit  an  appropriate  diagnostic  message  and  proceeds  These  error  messages 
are  to  appel^  on  the  dia^ostic  medium  precedi^  by  die  offending 
statement  The  processor  ^all  not  stop  upon  error  detection,  even  though  a 
ppition  of  its  output  may  be  in  e 

in  the  ease  of  nesting  errors,  the  processor  shaU  attempt  partial  recoveiy^ 
for  ex^ple^  scanning  the  nesting  levels  for  the  sanie  type  causing  tlm 
mismatch,  and  assuming  appropriate  statements  as  end^;  to  bring  the 
pmc^or  back  into  some  semblance  of  level-aUgiiment.  Statements  parts 
of  clauses  fpUowing  abo^,  cygle,  exit;  leave,  R^Rt4,  system*  stop  will  be 
recognized  as  being  unreachable,  an  error* 

The  exact  type  and  degree  of  nesting-error  recovery  is  not  covered  by 
this  specification*  The  appearance  of  output  listings  may,  therefore,  show 
variances  from  implemeiitatibn  to  implementation  until  standards  for 
recovery  are  provide 

Dia^ostic  messages  shall  describe  errors  in  the  user  iupui;  and  not  the 
inteniai  program  methods  used  to  discover  the  error. 


4.2  Detsdted  Software  Configurations  and  Modes  of  CperaUon 

Whether  the  CRISP  tystem  is  implemented  as  a single  program  with 
PDL,  FLOW,  and  translator  modes  selectable  by  control  data  or  whether 
each  processor  is  a separate  program  is  not  specified  by  this  document,  but 
may  vaiy  among  implementations.  Furthermore,  the  specifications 
contained  herein  do  not  require  any  prescribed  set  of  options  among  the 
processors. 

All  processors  may  selectively  disable  or  abbreviate  certain  types  of 
output  according  to  the  wishes  of  a user,  input  as  control  data*  However, 
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khei^e  shaiU  be  no  opiiph  that  can  alte^  or  semantic  value  of  the 

fomis  given  herein. 

Output  options  are  not  distinguished  as  separate  modes  of  operation  in 
the  cothing  descriptions,  bal  merely  as  variants  of  the  three  basic  modes. 


4.24  CRISP^PIIL  Mode 

Figure  4.1.1.1  is  a SMondJevfel-of-detail  HIPO  diagram  that  summarizes 
the  CRTSP-FDL  inputs,  processing  functions,  and  outputs^  Inputs  are  the 
source  filers)  bein^  processed  into  a fonnatted  listing  and  control  data  that 
selects  which  of  the  outputs  is  to  appear*  Processing  consists  of  cosmetizing 
source  lines,  accumulation  of  module  names  and  cro^reference  material, 
and  output  of  such  material  as  directed  by  control  data*  Output  consists  of 
(l)  a title  page;  (2)  a table  of  contents  (page  oi^r);  (3)  program  direetp 
(alphabetic  order);  (4)  tier  chart;  (S)  a listing  of  all  stub-status  modules;  (6) 
an  indented  listing;  (7)  a glossary  with  procedure  and  identifier  cross- 
references;  and  (8)  a statistical  summary  of  the  program  structure* 


4.2»14  Identifier  Cross-Referencing 

in  order  for  cataloguing  identifiers,  other  than  procedure  and  subroutine 
names,  to  occur,  those  identifiers  must  either  appear  first  in  a LET. *. be 
form,  or  else  contain  interspersed  periods  or  underscores  amid  alphanu- 
meric characters  (the  first  of  which  is  a letter),  as,  for  example,  “a,  b_3”. 
Eveiy  occurrertee  of  such  am  identifier  will  be  catalogued  accoiding  to  page 
and  line  number,  whether  in  procedure  descriptions  or  intervening  text. 


4.2.L2  Page  Ejection 

The  appearance  of  #n  beginning  a line  causes  the  ejection  of  a page  if  the 
remainder  of  the  page  contains  fewer  than  n lines,  when  n > 0;  the 
occurrence  of  #0  ejects  to  the  next  page  unconditionally. 


4,2*  L3  Intermodule  Text 

Text  appearing  between  procedure  modules  (see  Section  4.3.6:  initiated 
by  the  appearance  of  a ##  line,  terminated  by  #1^#)  is  copied  directly  to  the 
listing  scratch  file  without  cosmetizatibn  or  diagnostic  checking.  Each  line 
Is  scanned,  however,  for  identifiers  being  cross-referenced. 
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If  a line  appean  between  modules  and  begins  with  then  the  tejd  of 
that  line  Is  added  to  the  table  of 

4$rM  Boxed  CTbmments 

Within  a module  (see  Seetion  4.3iS)^  a line  containing  only  the  charaeters 
"<•'*  (exc<qpt  for  cosmeHi:s)  ^uses  the  lines  following  it  to  be  turned  into 
'‘boxed”  comments,  up  to  the  occurence  of  a line  With  only  on  it 

The  input 

<*- 

. forms 

p segment  pf  \ ' 

•*  cominents.  . 

:*> 

would  appear  pn  putj^ 

,»'•  ■ , , ' ■ ■ ‘ \ ■ 

<*  This  text  forms  ♦> 

<♦ -s.  segment  ' of  . ■■■*>  < 


<*  comments.  *> 


In  converting  text  for  ‘‘boxing/*  the  first  line  and  last  lines  are  converted 
to  <♦»♦•,»  the  width  being  appropriate  to  the  boxed  comments. 

Boxed  comments  are  indented  to  the  current  nested  level  Since  the  entire 
block  of  text  must  be  processed  to  determine  the  box  widths  buflfer  size  may 
limit  the  number  oflihes  that  may  be  so  boxed.  In  such  cases*  each  buffer 
load  is  boxed  according  to  the  liiaximum  width  of  text  in  that  buffer. 

4v2J»5  Update  Provisions 

In  an  “umtar”  option,  the  asterisk  in  column  1 within  a module  (see 
Section  4.0^1)  will  be  converted  to  a period*  When  this  occurs*  a comment 
is  generated  containing  the  current  date*  and  ai^ed  to  the  module  ender 
statement  (replacing  any  previous  comment).  In  this  way^  the  date  of  last 
approved  update  is  recorded.  The  modiiie  header  comment  often  contains 
the  original  design  date. 

4.2J.6  Right*Justified  Text  - 

The  appearance  of  a backslash  on  a line  causes  both  the  backslash  and 
the  text  to  its  right  to  be  right^justified.  This  is  a convenience  in  recording 
revision  numbers  to  statements*  or  indices  for  ease  in  locating  certain 
features*  If  the  backslash  appears  inside  a block  of  statements  being 
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scanned  for  “boxing/'  initiated  by  lines  containing  "<♦“  and 
respectively,  then  only  the  text  left  of  the  backslash  is  used  to  determine 
the  appropriate  box  width.  The  “•>*'  is  omitted  on  such  right-justified 
lines; 

4;2*L7  Output  Listing 

Source  lilies  input  between  a module  header  and  module  ender  are 
transferred  to  a listing  scratch  file  indented  and  cosmetized  according  to 
the  type  of  structure  in  which  nesting  occurs.  These  are  illuiitrated  in 
Section  4.3.  The  statement-continuation  signal  (&)  at  the  end  of  a line  is  not 
prints  bn  the  output  lining,  but  is  placed  on  the  cosmetized  reinpiit  file, 
in  case  that  file  is  saved  for  use  as  a future  source  input;  continued  lines  are 
indented  so  as  to  distinguish  them  from  the  first  line  in  the  continued 
statement. 

Each  line  of  a module  is  counted  and  used  to  aid  the  generation  of  page 
numbers  for  the  directory  and  table  of  contents.  Each  module  will  begin  a 
new  page,  as  will  any  narrative  that  follows  a module  end  and  a iiew 
module  header.  (Each  module  end  signals  a page  advance.)  The  output 
report  starts  the  GRISP-PDL  listing  at  page  1 (the  table  of  contents  and 
front  matter  are  given  foman  numeral  page  numbers).  Record  numbers  of 
the  source  fi.le(s)  are  affixed  to  each  corresponding  listing  llne^  at  the  left. 
The  format  of  the  listing  is  shown  in  7. 7.2.6. 

412. 1.8  Program  Tier  Chart 

The  program  tier  chart  is  a listing  of  the  program  structure  and 
hierarchy.  Within  each  module,  all  modules  invoked  by  that  module  are 
listed  indented  to  show  subordination.  The  tier  chart  is  prepared  from  data 
saved  during  statement  scan  processing  and  written  onto  a report  scratch 
file,  in  the  format  given  in  7.7.2. 4. 

4.2. 1.9  Stub  Status  Report 

After  the  tier  chart  is  written,  the  saved  cross-reference  data  is  queried 
for  missing  procedures  and  subroutines,  for  modules  identified  currently  as 
stubs,  and  for  modules  given  for  which  no  invocation  has  appeared.  A 
listing  of  these  Is  also  written  onto  the  report  file,  annotated  by  that  current 
status.  The  format  is  shown  in  7.7.2.S, 


Each  page  of  the  tier  chart  and  stub  report  is  given  the  next  consecutive 
Roman  numeral  The  tier  chart  follows  the  table  of  contents /directoiy  in 
the  output  report  listing. 

4.2.1-10  Table  of  Contents  and  Directory 

The  only  significant  difference  between  a table  of  contents  and  a program 
directory  is  the  key  on  which  the  module  identifiers  are  sorted.  When 
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sorted  by  page  number^  the  report  lining  is  the  table  of  contents;  when 
sorted  alphabetically  by  module  natne^  the  directory  results.  When  both  are 
generated  the  table  of  contents  precedes  the  directoiy.  The  formats  for 
these  appear  in  7, 7.2.2  and  7, 7.2.3.  Both  of  these  will  appear  before  the  tier 
chart.  IPagination  of  this  material  will  be  Roman  numerals. 

4 i Module  and  Identifier  Cross-References  and  Glossary 

Once  the  entire  source  program  has  been  scanned*  then  all  of  the  cross* 
references  have  been  accumulated.  At  this  point*  the  Usting(s),  glossary*  and 
cross-references  are  generated.  The  formats  for  the  glossary  and  cross- 
references  are  shown  in  7.7.2:7. 

4.2.1«I2  CRISP-PDL  Report  Output 

The  output  report*  in  its  fullest  form*  consists  of  the  following  sections  or 
parts*  in  order; 

• Title  page 

• Table  of  contents 

• Program  directory 

• Tier  chart 

• Stub  status  report 

• Intermodule  text 

• Cosmetized  source  listing*  first  module 

• Intermodule  text 

• Cosmetized  source  listing*  second  module 

• ... 

• ...  ■ 

• Crass-references  and  glossary 

• Usage  statistics  summary 

The  first  four  items  listed  above  are  given  Roman  numeral  page  numbers, 
and  the  rest*  Arabic  numbers.  The  formats  for  each  of  these  sections  or 
parts  may  be  found  in  7.7>2  of  this  specification. 

4.2.2  CRISPFLOW  Mode 

The  main  thrust  of  the  processing  specification  is  already  stated  in  the 
preceding  sections  of  this  document.  Simply  said,  GRISPFLOW  produces 
ANSI  standard  flowcharts.  The  flowcharts  are  drawn  one  to  a page*  with 
boxes  and  textual  material  sized  to  fit  on  such  a page.  CRISPFLOW 
produces  structured  flowcharts  only,  and  does  not  recognize  any  control- 
logic  directives  except  those  prescribed  in  Section  4.3. 
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Flowlines  connecting  boxes  conform  to  standards  set  forth  in  Section  2.1, 
in  that  decision  collecting  nodes  are  located  directly  under  the  vertex  of 
their  corresponding  predicate  node,  and  all  branches  are  labeled  in  case 
order  from  the  left  Loop-collecting  nodes  and  decision-collecting  nodes  are 
distinguishable  (the  latter  being  filled  in,  the  former  not).  Loop-exit 
flowlines  lead  to  subsequent  procedures  in  vertical  alignment  with  loop 
entry. 

There  are  no  off-page  connectors  drawn  by  this  version  of  CIUSPFLOW; 
all  chart  symbols  are  thus  scaled  to  fit  on  a single  page,  reducing  the  size  of 
chart  symbols  accordingly,  provision  is  made  by  this  specification  for 
not  charting  unsuitably  sized  modules,  although  a notification  may  appear 
on  the  diagnostic  display  medium  in  such  cases.  Implementations  may  elect 
to  draw  off-page  connectors  for  cases  without  violating  this  specification. 

The  flowchart  symbols  (‘'boxes’")  plotted  by  CRISPFLOW  will  have 
variable  dimensions,  but  the  standard  width-.height  aspect  ratios  required  by 
ANSI  are  sadsfied,  This  allows  for  the  potentially  different  lengths  of  text  of 
each  statement  to  fit  into  its  box  most  appropriately.  The  letters  “T'*  and 
“F”  are  drawn  to  annotate  the  true  and  fahc  branches  from  every  binary 
decision  box  (which  go  to  the  left  and  right,  respectively).  The  index  of  a 
CASE  clau.se  appears  to  the  left  and  below  the  intersection  of  the  clause’s 
input  flowline  with  the  "distribution  bus”  flowline. 

Comments  are  discarded  by  CRISPFLOW,  except  those  following  a do, 
CALL,  or  CALLX  invocation,  following  if  or  CASE  predicates,  in  at  and  fork 
stnictures,  or  appearing  in  a module  header  or  ender.  fn  invocation 
statements,  the  text  of  the  comment  is  inserted  into  the  corresponding 
striped  box  as  additional  annotation.  The  date  is  reproduced  at  the  right 
top  of  the  flowchart  page  to  aid  in  location  of  charts;  this  date  is  the  text 
string  found  in  the  comment  field  of  the  module  header  or  ender  (both  are 
entered,  if  present).  No  analysis  is  made  of  this  string  to  verify  its  correct 
format  as  a date.  Comments  after  IF  and  case  predicates  appear  as 
annotations  to  flowlines. 

Identification  numbers  and  cross-reference  information  appear  above  the 
right  and  left  edges  of  tjieir  box,  lespectively,  as  regulated  by  ANSI 
standard  conventions. 

Text  from  all  source  lines  continued  using  an  ampersand  (s)  as  the  final 
non-blank  character  is  inserted  into  a single  flowchart  box  on  output 
(cosmetics  removed).  Output  will  be  separated  into  multiple  lines  within 
the  box,  broken  at  appropriacc  spaces.  The  ampersand  does  not  appear  on 
the  output.  The  sample  program  charted  in  Figure  4.2.2. 1 illiKStrates  most 
of  these  features.  Other  outputs  of  CRISPFLOW  are  shown  in  Section  4.3. 


PBOCEDUHEt  SAMPLE  <*16  SEPT  75* > MODI  1.3.5 

.1  IF  (UNALLOCATED^ 

.2  CASE  (MODE) 

(11 

.3  STl 

12) 

.4  ST2 

.5  ST3 

(3) 

.6  ST4 

ENDCASLS 

.7/Sl  CALL  OPEN  (MODE)  <*CHANNEL  IS  MODE  NUMBER. *> 

(ELSE) 

.6  LOOP  WHILE  [AVAILABLE) 

.9/XS2  CALLX  HEAD |CHR|<*REAO  CHARACTEB*> 

.10/S3  CALL  WHITE (CilR)<*WRltE  CllARACTER*> 

REPEAT 

ENOIF 

,11  DO  CLOSE<*MESSAGE  SENT*> 

,12  DO  RELEAGE< ‘DISCONNECT  CHANNEL*> 

ENDPBOCEOUHE 


Rgure  4.2.2.I.  SAMPLE  procedure  illustrating  flowcharting  features 
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4.2.3  CRISP  Translation  Mode 

The  CRISP  translator  accepts  a source  input  stream,  recognizes  and 
extracts  elements  of  kej’word-initiated  statements  and  structures,  and 
outputs  target-language  code  in  replacement  Translators  need  not  be 
single-pass  processors;  in  fact,  REQUIRE  and  macro  features  require  more 
than  one  pass. 

Base-language  source  Statements  are  first  stripped  of  comments  and  then 
passed  directly  into  target  output.  Some  implementations  may  elect  to 
attach  the  comment  in  appropriate  target  syntax  to  the  output  statement.  If 
a base-language  statement  has  been  continued  over  many  lines  using  the 
CRISP  convention,  and  if  the  target  language  permits  line  continuation, 
then  appropriate  translation  will  be  made.  However,  the  user  is  considered 
responsible  for  otherwise  ensuring  that  base  language  elements  will  be 
correctly  interpreted  by  the  target  computer. 

In  some  implementations  (e,g„  CRTSP-assembly-language  processors), 
some  elements  within  CRISP  statements  not  recognized  as  part  of  this 
specification  may  be  parsed,  so  as  to  make  effective  use  of  the  CRISP 
formatting.  Notable  in  this  class  are  predicates  in  if  and  LOOP  structures, 
and  argument-passing  devices  for  subroutines  and  functions. 

However,  in  general,  this  specification  only  extends  to  implementations 
where  features  can  be  reasonably  accommodated.  Implementation  of 
FORK.  ..JOIN,  for  example,  may  not  he  implementabie  on  systems  not 
adaptable  to  concurrent  processing. 

Features  in  this  specification  may  be,  therefore,  deleted  to  form  CRISP 
subsets.  However,  no  translators  may  introduce  alternate  or  additional 
control  forms  and  remain  consistent  with  this  specification. 

Semantics  and  syntax  of  each  CRISP  form  are  contained  in  the  detailed 
language  specifications  in  Section  4.3,  below. 


4.3  Detailed  CRISP  Language  Specifications 

This  section  specifies  the  CRISP  structures,  their  syntax,  and  the  semantic 
value  of  each.  Each  construct  is  illustrated  with  a listing-source  form 
(which  may  also  be  used  as  reinput  to  CRISP  processors)  and  a 
corresponding  flowchart.  The  listing  forms  show  an  indented  format  that 
also  contains  vestigial  control-flow  lines  to  aid  in  readability.  The  notation 
shown  was  dictated  by  the  limitation  of  listing  symbols  to  the  ASCII  set  of 
characters.  Listing  media  with  other  character  sets  may  well  have  alternate 
cosmetics.  The  listing  form  shown  is  otherwise  a part  of  this  specification. 
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The  structures  specified  in  this  document  need  not  all  be  implemented  in 
any  given  processor  at  any  one  time.  However,  any  processor  implementing 
a particular  control  structure  herein  covered  must  adhere  to  the  details  of 
this  specification  for  that  structure.  CRISP-PDL  and  CRISPFLOW 
processors  must,  In  addition,  accommodate  the  superset  of  all  CRISP 
subsets  implemented. 


4.3  J The  CRISP  Statement 

A statement  is  normally  a single  physical  source  line  or  input  record. 
However,  a statement  may  continue  over  more  lines,  if  needed.  Statement 
continuation  is  signalled  by  the  appearance  of  an  ampersand  (&)  at  the  end 
of  a line,  which  indicates  the  next  line  is  a part  of  the  current  statement. 

Source  lines  may  or  may  not  be  indented  or  have  cosmetic  annotations  in 
them;  these  are  ignored  by  processor.  In  addition,  source  statements  may 
have  a statement  number  and  cross-reference  designator  specified,  in  the 
format 

. statementnumber/ crossreference  cosmetics  statementproper 

Statement  numbers  are  usually  integers,  and  the  cross-reference  is  usually 
an  integer  or  alphanumeric;  no  spaces  are  permitted  with  this  format. 
Either  or  both  of  these  fields  may  be  present  or  absent;  if  the  statement 
number  is  absent,  the  period  may  also  be  absent;  if  a statement  number  is 
present,  the  period  will  appear  in  column  1;  and  if  only  the  cross-reference 
field  is  present,  the  virgule  (/)  will  appear  in  column  1.  An  asterisk  may 
alternately  be  used  for  the  period  in  column  1,  when  '‘change  bars"  are 
used  to  indicate  diflFerences  between  current  and  previous  versions  of  a 
procedure.  CRISP-PDL  and  translators  do  not  process  statementnumber  or 
cosmetics  fields,  but  recognize  them  so  as  to  be  compatible  with 
CRISPFLOW.  Additionally,  translators  use  the  statement  and  module 
numbers  in  require  and  display.  See  Section  4.2.2  for  details  on  usage  of 
these  fields  by  CRISPFLOW  and  Sections  4.3.11  and  4.3.26  for  usage  by 
DISPLAY  and  REQUIRE. 

The  statementproper  of  an  input  statement  begins  either  in  column  1 or 
with  the  first  non-cosmetic  character  after  the  first  space  (or  other  cosmetic 
on  a line).  Comments  are  not  considered  cosmetic.  The  characters  that  are 
considered  in  this  specification  to  be  cosmetic  are:  space.  **:'**W\ 

“<”  not  followed  by  when  not  preceded  by  “♦**,  and  when 

not  in  column  1.  Implementations  not  having  these  characters  may  make 
suitable  substitutions.  Characters  “l'',  and  are  not  considered 

cosmetic  in  continued  lines. 
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4.3,2  CRISP  Keywords 

The  set  of  CRISP  keywords  (capitalized  in  the  remainder  of  Section  4.3 
for  emphasis)  are: 


ABORT 

ENDCASES 

FUNCTION 

REPEAT 

AT 

ENDPUNCTION 

IF 

REQUIRE 

CALL 

ENDIF 

JOIN 

RETURN 

CALLX 

ENDMACRO 

LEAVE 

STOP 

CANCEL 

ENDPROCEDURE 

LET 

STUB 

CASE 

ENDPROGRAM 

LOOP 

SUBROUTINE 

CYCLE 

ENDSUBROUTINE 

MACRO 

SYSTEM 

00 

ENDTO 

NORMAL 

TO 

DISPLAY 

ENOWHEN 

OUTCOME 

WHEN 

ELSE 

EXIT 

PROCEDURE 

Left  parenthesis. 

ENABLE 

FINISH 

PROGRAM 

Percent,  % 

ENDAT 

FORK 

/ 


These  specifications  present  keywords  as  capitals;  however,  on 
implementations  that  permit  lower  case  and/or  underscoring,  keywords 
may  appear  on  the  output  either  in  upper  or  lower  case  and,  perhaps, 
underscored  or  otherwise  emphasized,  depending  on  the  implementation. 
When  available,  upper  and  lower  case  characters  have  equal  syntactic 
value. 

All  keywords  are  terminated  by  space,  left  parenthesis,  colon,  or  an  end- 
of-line.  The  statement  kejword  must  appear  as  the  first  non-cosmetic  entrj' 
of  a statement.  Keywords  may  not  he  abbreviated. 


4.3,3  Comment  Delimiters 

Comments  in  CRISP  are  denoted  by  the  delimiters  and 

Comments  may  appear  anywhere  within  a statement  after  the  ke)word,  if 
any. 

The  final  "♦>”  need  not  appear  if  the  comment  extends  to  the  end  of  a 
statement.  Comments  may  extend  over  any  number  of  lines  when  the  line- 
continuation  signal  appears  (see  Section  4,3.3,  below).  The  opening 
delimiter  may  appear  inside  a comment. 

An  arbitrary  number  of  input  lines  preceded  by  a line  rr-ntaining  only 
followed  by  a line  containing  only  will  be  recognized  as  a 

comment  block,  and  need  not  use  line-continuation  signals  (&),  See  Section 
4.2,1,4  for  CRISP-PDL  formatting  of  comment  blocks. 
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Comments  are  scanned  by  CRISP-PDL  for  identifier  references,  and  some 
comment  fields  are  used  by  CRISPFLOW.  See  Sections  4.2,1-1  and  4,2.2, 
above,  for  details, 

4.3.4  Non-CRISP  Statements 

Source  input  statements  that  do  not  begin  with  unc  of  the  above-named 
keywords  are  permissible,  and  are  processed  directly  into  the  output  (with 
cosmetics  and  indentation  added  in  CRISP-PDL). 

4.3.5  Program  Modules 

Several  keywords  (program,  procedure,  TO,  function,  macro,  and 
subroutine)  initiate  program  segments,  hereinafter  called  “modules,” 
which  extend  to  their  corresponding  end  statement.  The  initiating 
statements  are  herein  called  “module  headers”  and  the  closing  statements, 
“module  enders.” 

A typical  example  of  the  header  syntax  is  the  following: 

PROCEDURE : nttmc  \<*datcl*>]  [MOD#^/£ru;cy] 

Module-header  statements  may  contain  a cross-reference  number  following 
the  optional  substring  “MOD#”,  continuing  to  the  end  of  the  statement. 
These  are  not  ased  by  the  CRISP-PDL  processor  but  by  CRISPFLOW 
(Section  4.2.2)  and  translators  (Section  4.2.3).  A typical  module  ender  syntax 
is  the  following: 

ENOPROCEDURE  \<^date2*>\ 

The  header  and  ender  date  fields,  being  comments,  are  not  used  by  CRISP 
translators  but  by  CRISPFLOW  to  label  flowcharts  and  by  CRTSP-PDL  to 
record  design  and  update  times.  The  module  flowchart  format  is  defined  in 
Figure  4.2.2. 1. 

Modules  may  not  be  nested  within  other  modules,  but  may  be  linked  to 
via  DO,  CALL,  CALLX,  and  function  invocations  discussed  below. 

Thc!  general  format  of  a module  listed  by  CRISP-PDL  is 

mmiuhhcadcr 

structure 

structure 


modulcender 
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The  listing  itidentalion  shown  is  twelve  spaces,  to  account  for  a .dda/aaaas 
field  at  the  left  margin,  where  d represents  a digit,  a represents  an 
alphanumeric,  and  s denotes  a space.  The  module  header  begins  flush  with 
the  left  margin.  On  abnormal  and  paranormal  exits  from  a module,  column 
12  will  contain  a colon  (:),  as  in  Section  4.3.7,  below.  The  module  ender 
begins  in  column  13  except  when  abnormal  or  paranormal  exits  are  present, 
in  which  case  it  begins  in  column  12. 

A structure  is  a body  of  CRISP  consisting  of  one  or  more  statements  or 
modular  forms  as  detailed  in  the  succeeding  subsections  of  this  section. 
Output  listing  cosmetics  for  structures  nested  within  structures  retain  the 
cosmetics  of  the  outer  structures. 


4.3.6  Intermodule  Text 

Textual  material  in  the  source  input  prior  to  the  first  module  header,  or 
between  a module  ender  and  the  next  header,  is  permitted,  provided  such 
text  is  preceded  and  followed  by  lines  containing  the  characters  ##  and  ###; 
such  lines  are  treated  the  same  as  comments,  in  that  CRISP-PDL  examines 
this  text  for  occurrences  of  let. ..BE  statements  and  identifiers  containing 
period  and/or  underscore  as  spacers,  and  for  lines  beginning  with  # 
followed  by  text.  Both  CRISPFLOW  and  CRISP  translators  ignore  such 
text.  See  Section  4.2.1  for  further  information. 


4.3,7  ABORT  Statement 

The  ABORT  statement  may  appear  within  a module: 

mochlehetidcr 


< ABORT  l&hcl 


modulccndcr 

Tn  the  listing,  the  proper  numl^er  of  to  fill  the  indentation  level  at  the 
abort  nesting  level  will  appear  past  column  15,  All  svibsequent  lines  will- 
have  to  denote  an  exit  flowline  in  column  12,  'i'h.;  module  cnrfcr  begins 
in  column  12  when  an  abort  has  appeared 
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CRTSPFLOW  draws  the  terminal  symbol  with  label  printed  inside,  as 
below; 


CRISP  translators  generate  program  transfers  to  the  labeled  statement 
elsewhere  in  the  code,  with  proper  subroutine /procedure  linkage-recovery 
as  may  be  necessary.  The  label  is  not  checked  syntactically  as  part  of  this 
specification. 


4.3.8  AT  Structure 

The  AT  structure  sets  up  linkages  to  procedural  blocks  that  may  he 
initiated  by  contingency  events  occurring  within  the  first  body  of  code. 


: stTucturcJ 

: ->  (rvJORMAL) 
struct  urc2 

;...ENDAT 


Any  number  of  structures  may  appear,  introduced  by  ceen/s.  Each  event 
appears  in  the  evcntlist,  separated  by  commas  if  more  than  one  event-, 
events  may  be  restricted  in  some  implementatioas  to  appear  in  a particular 
order. 


Tn  order  for  the  AT  structure  to  be  nestable  within  other  at  (and,  perhaps, 
when)  stnictures,  it  may  be  necessary  for  AT  and  ENDAt  to  save  and  restore 
interrupt  vectors  at  nmtime,  or  such  other  mechanisms  used  in  the  target 
language  to  assure  program  correctness  in  control 


Appendix  C 


335 


CRISPFLOW  produces  the  flowchart  below  for  the  AT  structure; 


The  interruptible  structurel  is  enclosed  within  a box  as  shown>  drawn  to 
proper  scale  {Reference  7,2,3).  Substructures  are  drawn  inside  this  box  in  a 
normal  manner,  except  when  that  structure  is  a single  statement.  In  this 
case>  only  the  single  box  is  drawn. 

CRISP  translators  convert  the  eventlist  into  dedicated  contingency 
internipt  arming  target  code  (or  equivalent)  for  such  conditions  as  endfile, 
conversion  error,  overflow,  etc.  Execution  of  the  normal  branch  disables 
these  interrupts,  as  does  entry  into  any  one  of  the  contingency  event  code 
bodies.  See  Section  4.3.22  for  further  discussion  of  NORMAL. 

4.3^9  CALL,  CALl.X,  and  DO  Statements 

CALL,  CALLX,  and  DO  Statements  invoke  local  subroutines,  externa] 
subroutines,  and  singly  occurring  procedure  bodies,  The  listing  of  such 
statements  causes  no  indentation. 

CALL  .subnatnc 

CALLX  [<  ♦/;/«« mt»n/*>] 

DO 

The  subname  field  must  be  in  base  language  syntax  for  local  subroutines 
(ones  within  this  compilation);  xsubnamc  must  likewise  be  convenient  for 
subroutines  compiled  separately  or  in  libraries;  both  CALLX  and  CALL  may 
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not  be  needed  for  a given  implementation.  The  subname  and  xsubname 
fields  may  have  argument  subfields  in  some  implementations. 

The  name  field  may  be  any  string  of  characters^  but  may  not  be  used  to 
designate  passing  of  arguments. 

CUISPFLOW  produces  the  flowcharts  below: 


Translators  encountering  GALL  and  CALLX  statements  output  appropriate 
SUBROUTINE  linkages.  The  DO  statement  may  generate  a linkage  to  TO  or 
PROCEDURE  modules  named  by  name  within  this  compilation*  or  may 
substitute  that  module  body  directly  inline  into  the  target  code  stream 
(translated  as  per  these  specifications). 

4i3.l0  CASE  Structure 

The  CASE  structure  implements  a multiple  branch  on  an  index  variable 
(or  other  discrete-valued  variable). 


CASE  {index)  [<*commcntO*>] 
: ->  i value  I)  [<*  comment  J*>] 

: stntcturel 

{vahc3)  [<*i:ommcni2*>] 

: structures 


. . ENDCASES 


The  valuei  fields  represent  valid  values  of  the  index  and  may  appear  in  any 
order;  several  values  may  appear,  separated  by  commas,  in  one 
parenthetical  form.  ELSE  may  appear  in  lieu  of  the  final  value  (see  Section 
4.3.12),  The  commenti  fields  are  optional,  and  are  used  only  by 
CRISPFLOW  to  annotate  flowcharts. 
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CRISPFLOW  produces  the  following  flowchart: 


CRISP  translators  generate  code  to  branch  to  appropriate  blocks  of  code 
as  specified  by  of  index.  If  an  else  clause  is  present,  all  values  of 

index  other  than  those  cited  invoke  the  ELSE  clause;  otherwise,  such  values 
cause  runtime  error  actions  appropriate  to  the  target  language. 

The  CASE  structure  permits  the  selection  of  any  one  of  several  specified 
code  bodies  for  execution,  based  on  the  value  of  a single  scalar  discrete- 
valued variable.  Each  case  entry  is  labeled  with  the  scalar  value  of  the 
index  required  to  cause  execution  of  that  case.  These  scalar  labels  need  not 
be  in  consecutive  order,  nor  must  all  possible  discrete  values  in  a range  be 
present.  Any  discrete  data  type  recognized  by  the  target  language  as  an 
ordered  set  is  permissible,  such  as  integers  and  characters.  However,  the 
pre-processor  will  not  necessarily  perform  a check  of  the  index  data  type 
versus  the  case-label  scalar  type,  nor  will  all  discrete  data  types  permissible 
in  a base  language  necessarily  be  supported  by  a CRISP  translator. 

The  ELSE-case  is  a default  specification,  and  is  optional  within  the 
structure.  If  an  ELSE-case  is  specified,  then  any  value  of  the  index  not 
corresponding  to  a case  label  upon  execution  causes  the  ELSE  code  body 
(which  may  be  null)  to  be  executed.  If  no  ELSE-case  appears  within  the 
stnicture  at  all,  then  an  index  value  outside  the  stated  set  of  indices  causes 
a nmtime  error  message  to  be  output  on  the  job  nm  stream  and 
appropriate  recovery  action  for  the  target  language. 
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Several  case  labels  may  appear  in  the  same  clause  header,  to  cause 
execution  of  the  common  case  body  for  the  specified  values  of  the  index. 
Commas  separate  the  case  labels  in  such  instauces, 

Duplicate  case  labels  cause  translator  diagnostic  error  messages  to  he 
printed, 

4,3*11  DISPLAY,  CANCEL,  and  ENABLE  Statements 

During  the  translation  of  a CRISP  source  into  target  statements,  the 
statement 

ENABLE  MODULE  COUNT 

causes  a set  of  special  trace  execution  cnunters  to  be  declared,  one  for  each 
flowline,  During  execution  of  the  target  code,  rach  traversal  of  a flowline 
causes  incrementation  of  the  corresponding  counter. 

The  CRISP  statement 

DISPLAY  THRU  LEVEL  inta^cr 

outputs  target  code  that,  when  executed,  prints  the  values  accumulated  in 
the  counters.  Each  such  count  is  tagged  with  the  Dewey-decimal  identifier 
of  the  corresponding  program  step.  The  integer  value  selects  the  module 
nesting  depth  of  the  display  as  determined  by  the  decimal  count  in  the 
Dewey-decimal. 

The  statement 

CANCEL  MODULE  COUNT 

disables  the  creation  of  fiowline  execution  trace  logic.  The  use  of  ENABLE- 
CANCEL  pairs  permits  probing  of  selected  portions  of  the  program  during 
development  testing. 

The  default  condition  at  the  beginning  of  translation  is  the  enable  mode. 
For  fully  verified  programs,  the  overhead  setting  up  and  incrementing 
counters  must  be  removed  by  prefixing  the  source  program  with  the  CANCEL 
statement. 

4,3,12  ELSE  Statement 

The  ELSE  keyword  may  appear  in  IF  or  case  structures  to  introduce  the 
default  clause.  Parentheses  are  optional: 

ELSE 

(ELSE) 
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CRISPFLOW  labels  the  ELSE  flowUne  in  binary-iE  stnictures  and 
“else''  in  multiple-iF  and  CASE  structures.  The  comment  field  annotates 
this  flowliiie  additionally,  if  present 

Upon  encountering  ELSE,  translators  generate  an  unconditional  transfer 
to  the  stnicture  end,  followed  by  a transfer  label  for  the  ELSE-clause. 


4.3,13  EXIT  Statement 

The  paranormal  exit  statement  may  appear  within  the  TO  or  procedure 
stmctiire  and  the  macro  stnicture.  The  CRISP-PDL  listing  format  is  the 
same  its  for  abort.  In  a TO-moditk%  for  example, 


TO  Airing 


EXIT 


ENDTO 


The  number  of  which  will  appear  is  that  required  to  fill  the  space  from 
the  indenting  level  of  exit  hack  out  to  the  procedure  first  level  AH 
subsequent  lines  have  a colon  (,•)  in  column  12  and  the  final  end  will  begin 
in  column  12  Jis  shown  above. 

CRISPFLOW  draws  the  terminal  symbol  with  EXIT  in/eger  enclosed,  as 


EXIT  [/nreperi 


Translators  set  the  outcome  flag  to  the  value  of  integer  and  branch  to  the 
code  generated  by  the  module  ender,  exit  may  appear  at  any  level  of 
decision  or  loop  nesting  within  the  stnicture;  exit  n'lay  not,  however,  be 
used  to  escape  from  more  than  one  nested  macro  or  procedure  module  at  a 
time. 
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4.3J4  FINISH  Statement 

The  FINISH  statement  appears  as  the  last  line  in  a CRISP  source, 
beginning  in  column  1,  as 

FINISH 


AH  clean-up  and  operations  required  to  terminate  processing  are  performed 
in  the  program  being  processed  as  well  as  for  the  processor  itself.  No 
symbol  is  drawn  in  CRISPFLOW. 

4.3 J5  FORK  Structure 

stnictures  within  this  syntax  are  bounded  at  the  top  by  FORK  and  at 
the  bottom  by  Jom  Within  this  construct,  concurrent  processes  are 
identified  by  clauses  introduced  by  parenthesized  strings: 


FORK  (<  * com  tumtO*  > ) 
: ; .vlrurturcJ 

: : sfnjctur<!2 


. JOIN 

Any  number  of  strurAures  may  appear,  introduced  by  a parenthesized  string, 
CRTSPFLOW  produces  the  following  flowchart: 


com  memo 


string  1 


commenti 


I 1 

I structured  j 

m.  ■■Hii  m*m  wJ 


strmg2  | comrtfem2 

I 

! structured  ^ 

1 I 
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FORK. . .JOIN  will  only  appear  in  translators  for  languages  that  permit 
concurrent  operations  of  the  type  inferred  by  the  flowchart.  Stnngs  are 
necessary  to  label  tasks  for  concurrent  execution.  JOIN  terminates  the 
concurrent  mode  for  ail  of  these  tasks,  and  only  when  all  have  reached  the 
JOIN. 

4.3,16  FUNCTION  Structure 

Ti.a  FUNCTION  structure  permits  definition  of  functional  modules  if 
supportable  by  the  target  language.  If  local  and  external  functions  must 
have  different  syntaxes,  the  keyword  xfunction  may  be  added. 

On  input  and  listed  output,  function  begins  in  column  1 (see  Section 
4.3.5  for  general  header  form)t 

FUNCTIONC/nrtmc[<*rfflfc;*>l  [MOD#  dewey] 

sirttciure 

ENDFUNCTION  [<*datc2*>] 

The  ENDFUNCTION  keyword  normally  appears  listed  in  column  .13,  but  moves 
to  column  12  if  an  extra-normal  exit  (return)  has  occurred  in  the  module. 
The  designator  C denotes  a colon  (:)  or  space. 

CRISPFLOW  draws  entry  and  exit  terminal  symbols  labeled  as  shown 
below: 


dewey 


fname 

X, 

structure  | 


C 


~J1 

RETURN 


) 


dewey 
fname 
datel 
date2 
page. — of 


Functions  are  entities  that  are  potentially  separately  compilable. 
Variables  defined  within  a function  are  generally  not  accessible  to  the 
invoking  program.  Therefore,  provisions  for  passing  arguments  or 
parameter  lists  are  hereby  specified.  Functions  may  invoke  subprocedures 
by  using  the  DO  statement  as  long  as  those  procedures  are  defined  as  TO-  or 
PROCEDURE-blocks  Within  the  function  compilable  unit.  Functions  may  also 
invoke  subroutines  and  other  functions. 
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Each  function  name  is  a (unique)  name  to  be  assigned  to  the  function  in 
the  target  language  syntax,  Both  the  name  and  arguments  are  contained  in 
fname  and  passed  directly  without  analysis  by  the  translator  to  the  target 
language.  The  name  and  arguments  must,  therefore,  conform  to  the 
conventions  of  the  target  language. 

See  RETURN  {Section  4,3,27)  for  paranormal  exit.  Control  flow  reverts  to 
the  invoking  program  upon  encountering  the  RETURN  statement  in  the 
FUNCTION  body,  subject  to  the  same  rules  as  for  subroutines. 

Functions  may  be  invoked  by  the  usual  base-language  provisions  for 
functions,  if  any,  If  none  exists  in  the  base  language,  then  FUNCTiON-block 
capability  may  be  omitted  from  the  translator. 

4.3*17  IF  Stnicture 

The  generalized  if  structure  permits  the  logical  selection  for  execution 
of  one  among  a number  of  specified  code  bodies  within  the  structure: 

IF  iprcdicatel)  [<*commcntl*>] 
structure} 

: r->  {predicates)  l<.*commenf2*>] 

: Structures 


. . ENDIF 

Any  number  of  structures  may  appear,  introduced  by  a parenthesized 
predicate.  One  ELSE  or  (ELSE)  can  also  be  used  to  introduce  the  final 
structure  (see  Section  4.3.12), 

The  strticturc  (or  clause)  selected  for  execution  corresponds  to  the  first- 
encountered  true  condition  in  top-down  order*  All  conditions  tested  have 
logical  values  true  or  false.  Any  of  the  selections  may  lead  to  null  clauses, 
and  the  ELSE-clause  is  optional.  If  present,  the  ELSE-clause  u executed  as  a 
default  case  when  all  of  the  given  predicates  are  false.  The  ELSE  keyword 
need  not  be  stated  when  the  code  block  following  is  null* 

At  the  completion  of  execution  of  a given  clause  (as  signalled  by  the 
appearance  of  a new  clause  or  endif),  control  passes  to  the  end  of  the 
structure  (designated  by  endif). 

There  are  no  constraints  on  the  number  of  predicates  or  on  the  size 
(including  null)  and  number  of  clauses.  The  optional  parentheses  around 
ELSE  are  provided  for  consistency  in  appearance  with  other  predicates,  if 
the  programmer  desires. 
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CRISPFLOW  distinguishes  between  the  simple  single-predicate  form  and 
the  general  form.  The  single  predicate  form  (with  an  optional  commcnt2  on 
an  ELSE  statement)  is 


The  general  iF-form  appears  as  a multiple  branch: 


4.3.18  IF  Statement  and  Modifier 

A special  case  of  the  iF-stnicUire  may  be  used  in  situations  where  there 
is  a single  predicate,  the  default  case  is  null,  and  the  code  body  to  be 
executed  when  the  predicate  is  true  consists  of  a single  statement.  In  such 
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cases,  the  single-line  statement  is  placed  on  the  same  line  as  the  IF 
keyword,  and  SNDIF  is  omittedr 

IF  ijyraiiaitc]  .'itnltment 


The  statement  may  be  any  single-line  valid  construction  in  the  base 
language,  or  it  may  be  a DO,  CALL,  or  callx  statement.  The  statement  may 
not  begin  with  a comment 

IF  may  also  modily  exit,  leave,  CYCLE,  and  return,  as  in  the  example 
: < EXIT  integer  IF  {predicate) 

Such  a form  is  equivalent  to 

IF  [predicate) 

; EXIT 
: . . ENDIF 

CRTSPFLOW  will  produce  the  same  flowchart  as  would  be  obtained 
from  the  corresponding  longer  form.  If  a box  number  and  cross-reference 
field  are  designated,  the  box  number  is  put  on  both  symbols,  but  the  cross- 
reference  applies  only  to  the  statement  box. 


4.3.19  LET  Statement 

All  identifiers  signalled  by  the  presence  of  periods  and  underscores  are 
automatically  catalogued,  as  previously  described  (Section  4.2.1.1).  Other 
identifiers  may  he  identified  to  the  CRTSP-PDL  processor  for  subsequent 
cross-referencing  purposes,  using  the  statement 

LET  identifier  BE 

The  identifier  is  any  alphanumeric  (first  character  alphabetic),  and  string  is 
any  arbitrary  set  of  characters  (or  may  be  null);  identifier  may  contain 
periods  and  underscores,  if  desired. 

Subsequent  occurrences  of  identifier  in  the  CRfSP-PCL  source  program 
are  treated  the  same  as  identifiers  using  periods  and  underscores.  The  string 
appears  in  the  program  glossary;  it  provides  a means  of  defining  variable 
name  mnemonics,  data  type,  units,  and  other  pertinent  information  for  later 
reference. 

CRISPFLOW  and  CRISP  translators  ignore  the  let*.. BE  .statement 
altogether.  A let  statement  without  BE  is  always  assumed  by  all  processors 
to  he  a base-language  statement,  and  no  error  noted. 
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4p3.20  loop  Structures 

All  loops  in  this  syntax  are  bounded  at  the  top  and  bottom  by  the  verbs 
LOOP  and  REPEAT,  respectively.  Within  this  construct,  the  LEAVE  verb  may 
be  used  to  cease  iteration  and  to  continue  execution  at  the  statement 
following  REPEAT,  Similarly,  the  CYCLE  verb  may  be  used  to  start  the  next 
iteration;  that  is,  to  transfer  control  to  the  repeat  statement.  Multiple  LEAVE 
and  CYCLE  statements  may  appear  within  a given  loop. 

The  format  of  the  CRtSP-PDL  listing  is 

LOOP  ... 

t . . , 

! ... 

REPEAT. . , 

There  are  three  forms  of  valid  loop  structures,  and  variants  within  each 
form.  There  are  two  unindexed  forms  and  one  indexed  form.  The-se  are 

LOOP  WHILE  iprrdictile) 

! siructvte 

] . . REPEAT 

LOOP 

• structure 

'..REPEAT  IF  {predicate) 

LOOP  FOR  index  = cx)}rcs&\onl  [BY  e*;irc.vsrfm2]  TO 

1 structure 

1 . . REPEAT  WITH  NEXT  index 

In  the  first  of  these,  WHILE  may  be  replaced  by  UNTIL,  meaning  WHILE  NOT; 
in  the  second,  UNLESS  may  replace  IF,  meaning  IF  not;  and,  in  the  third,  a 
WHILE  or  UNTIL  phrase  may  replace  the  TO  phrase.  AU  expression.?  are 
assumed  to  be  in  target  syntax  already.  Tf  cxpression2  is  omitted,  a value  of 
unity  is  assumed. 

The  index  parameters  must  match  in  the  third  form.  The  value  of  the 
increment,  is  constant  throughout  the  iteration,  but  may  not  be 

zero  upon  mntime  entiy  into  the  loop;  is  re-evaluated  on  each 

iteration  of  the  loop  only  if  while  (or  until)  is  used. 

Upon  termination  of  indexed  iteration,  the  value  of  the  index  variable 
shall  be  the  first  such  value  encountered  violating  the  loop  predicate, 

CRTSPFLOW  draws  these  structures  as  depicted  in  Figure  4.3.20.1, 


(a)  LOOP  WHILE.  . . REPEAT 


(b)  LOOP  UNTIL,  , . REPEAT 


(cl  LOOP.  . . REPEAT  IF 


(d)  LOOP.  . .REPEAT  UNLESS  (e)  LOOP  FOR,  . .TO.  . . 

..  .REPEAT  WITH  NEXT 


Figuie  4.3.20.1.  CRISPFLOW  format  of  LOOP-REPEAT  structures 


A 
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The  LEAVE  statement  may  appear  nested  within  a loop  structure,  as 

LOOP  . . . 

I . . * 

! 

■ < _ * ^ LEAVE  [ mfL'gcr J 

: I ... 

: ! . . . 

: [..REPEAT... 

The  number  of  dashc.s  (-)  which  appear  on  CRISP-PDL  listings  is  that 
required  to  fill  in  from  the  current  indentation  level,  back  out  to  the  LOOP 
indentation  level.  Colons  (:)  appear  on  each  subsequent  line  within  the  LOOP 
stmcture  at  the  loop  indentation  level,  leave  may  only  be  used  to  escape 
iteration  of  the  innermost  loop  structure  containing  it,  and  the  leave 
directive  cannot  be  imbedded  within  procedures  invoked  by  DO  or  call 
(unless  LEAVE  appears  within  appropriate  LOOP -REPEAT  stmcture  boundaries 
within  the  procedure).  If  an  integer  follows  leave,  its  value  is  assigned  to 
the  OUTCOME  flag  when  executed.  When  such  is  the  case,  normal  loop 
termination  sets  OUTCOME  to  zero. 

CRTSPFLOW  charts  the  LEAVE  situation  using  on-page  connectors 
labeled  alphabetically  {a,  B,  C,  etc.)  as  shown  below: 


(a)  LEAVE 


lb)  »n  LOOP  WHILE  and 
LOOP  FOR 


(c}  In  LOOP  UNTIL 


(d)  LOOP, ..  REPEAT  IF 

LOOP. . . REPEAT  UNLESS 
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The  CYCLE  verb  may  also  appear  anywhere  within  the  LOOP. . .REPEAT 
structure,  and  at  any  level  of  decision  nesting  within  that  range.  CYCLE  may 
only  be  ased  to  control  iteration  of  the  innermost  loop  structure  containing 
it,  CYCLE  may  not,  however,  be  imbedded  in  procedures  initiated  by  DO  or 
CALL  (unless  CYCLE  appears  within  appropriate  LOOP. .. REPEAT  boundaries 
within  the  procedure), 

LOOP 


<-- CYCLE 


! , . REPEAT 

The  number  of  which  will  appear  is  that  required  to  fill  the  space  from 
the  indenting  level  of  CYCLE  back  out  to  the  LOOP  indenting  level. 

CRISPFLOW  draws  on-page  connectors  labeled  alphabetically  (a,  b,  c, 
etc.)  for  the  CYCLE  situation  as  shown  below; 


(a|  CYCLE 


lb)  In  LOOP  WHILE 

— L© 


Ic)  In  LOOP  UNTIL 


CRISP  translators  generate  an  unconditional  branch  to  the  beginning  of 
the  REPEAT  statement  for  the  CYCLE  statement. 
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4.3.21  MACRO  Structure 

The  MACRO  stnicture  defines  a module  for  direct  iasertion*  The  MACRO 
keyword  begins  in  column  as 

MACROC  temphte 

.•iinteturu 

ENDMACRO 

See  Section  4.3*3  for  further  details  concerning  module  header  format. 

CRISP  translators  have  a minima^  but  useful,  compile-time  text- 
substitution  macro  capability*  Macro  invocations  in  the  source  program  are 
signalled  by  the  appearance  of  an  escape  character  (%)  followed  by  a string 
to  be  replaced: 

. . . %string.  , . 

Such  occurrences  of  .yfring  that  *'match’*  a macro  template  (matching 
described  below)  will  he  replaced  by  structi4re  prior  to  generation  of  any 
code  output. 

The  macro  template  coasists  of  characters  that  must  match  correspond- 
ing characters  in  the  input  string  exactly,  except  in  positions  in  the  template 
where  markers  for  formal  parameters  occur.  These  markers  take  the  form 
%9;  they  designate  the  place  in  the  input  string  where  groups  of 
characters  are  to  be  extracted  and  passed  to  the  internal  macro  structure  for 
.substitution  in  places  correspondingly  marked  %i,  %2,  . , %9.  The  numbers 
of  characters  assigned  to  each  parameter  marker  are  determined  so  as  to 
make  all  other  characters  in  the  input  string  agree  with  template  characters. 
If  no  matching  is  possible,  the  %string  is  output  directly  as  target  syntax. 
See  References  7.2.1  and  7.2.2  for  further  details  on  template  matching 
based  on  the  STAGE2  macro  generator. 

MACRO-defining  modules  and  invocations  may  be  used  an) where  in  the 
CRISP  source  code.  Tn  particular,  an  invocation  may  precede  its  macro 
module  definition.  Macro  modules  may  contain  other  invocations,  but  may 
not  enclose  other  macro  modules  (nor  any  other  module  types,  for  that 
matter). 

Alternate  forms  of  the  macro  module  may  be  used  to  define  macros 
within  procedures,  subroutines,  functions,  and  programs.  These  are 

MEANS  .^^rinr^END 
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and 


%tcmfitate  MEANS 
Jitrudtnrc 
%END 

In  these  forms,  the  template  parameter  markers  are  designated  by  only  the 
escape  character  (%,  rather  than  %i);  the  ith  such  template  marker  is  used 
exactly  the  same  as  %/  in  the  MACRO  template;  up  to  9 may  appear.  The 
structure  (or  .9/ring  in  the  simple  one-line  form)  uses  the  same  conventions 
as  in  the  MACRO  structure,  viz,,  %U 

CRISP-PDL  and  CRTSPFLOW  operate  as  if  the  separate  MACRO  modules 
were  procedure  modules;  however,  the  alternate  forms  introduced  by  % are 
treated  by  CRISP-PDL  as  follows:  The  single-line  form  is  listed  at  the 
current  indentation  level,  and  the  multi-line  form  appears  as 


%t(/rnphid  MEANS 
stmeturd 

: . . %END 

CRISPFLOW  generates  a separate  one-page  flowchart  for  each  such  macro 
dehnitioa 

See  EXIT  (see  Section  4,>3.13)  for  paranormal  exit  information, 

4<3.22  NORMAL  Statement 

The  NORMAL  keyword  may  appear  in  at  or  when  structures  to  introduce 
the  clause  that  executes  when  contingency  or  priority  event  interrupts  have 
not  occurred,  ft  may  also  occur  in  OUTCOME  structures,  in  which  case  it 
corresponds  to  a zero  value  of  the  outcome  flag.  Parentheses  are  optional: 

NORMAL  l<  • com  vient*  > ] 

( NORMAL ) [<  ♦ enm  meu  f • :>] 


For  the  AT  structure,  entry  into  any  of  its  clauses  (including  normal) 
disconnects  the  contingencies.  For  the  WHEN  structure,  each  clause  identifier 
(including  normal)  causes  the  translator  to  generate  code  to  dear  the 
interrupt  logic  of  the  event  structure  above  it  to  return  to  the  point  of 
interruption,  and  to  label  the  entry  point  to  the  current  event  clause. 

The  NORMAL  clause  need  not  appear  in  at  structures  when  it  introduces  a 
null  clause,  but  must  always  appear  in  the  when  .stnicUire,  even  with  a null 
clause. 
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4,3.23  OUTCOME  Flag  and  OUTCOME  Structure 

CRISP  has  a special  internal  flag  which  can  be  set  only  by  RETURN,  exit, 
LEAVE,  and  the  normal  module  ender.  Each  of  the  paranormal  exits  has  an 
optional  integer  field  that  is  assigned  to  the  OUTCOME  flag  on  execution  of 
the  escape.  Translators  emit  code  for  the  normal  module  ender  to  clear  the 
flag  to  zero  if  any  paranormal  escape  has  set  the  flag  within  the  module. 
Similarly,  if  other  paranormal  exits  occur  unlabeled  by  an  integer,  they,  too, 
cause  the  flag  to  be  cleared.  In  this  way,  the  OUTCOME  flag  may  be  used  to 
record  which  of  several  paranormal  escapes  from  a module  or  loop  was 
taken. 

This  flag  can  only  be  tested,  using  the  OUTCOME  structure 

OUTCOME 
: “>  (urr/Mc*/) 

: structural 

; ->(tvi/rur2) 

: strut' fura2 


: . . ENDCASES 

The  OUTCOME  ke>'vvord  is  treated  in  all  processors  exactly  as  if  CASE 
(outcome)  had  appeared,  except  that  the  internal  flag  variable  is  referenced, 
NORMAL  may  replace  a value  of  zero  in  a clause  header. 

4.3,24  PROCEDURE  and  TO  Modules 

The  PROCEDURE  and  TO  ke>'Words  introduce  modules  invoked  by  the  DO 
verb.  The  two  keywords  are  equivalent:  endto  and  ENDPROCEDURE  are 
likewise  equivalent,  and  any  combination  of  header  and  ender  pairs  is 
permitted. 


PROCEDUREC  namc.[<*(hiej*>]  [MOD#  dcwcij] 

structure 

ENDPROCEDURE  (<*rfnfc2,>l 


TO  name  [<.*dalcl*>]  [MOD#  tluweij] 

Structure 

ENDTO  [<.*(lfitc2*>] 

Procedures,  for  the  purposes  of  this  specification,  are  bodies  of  code 
whose  scope  of  variables  is  that  of  the  module  which  has  invoked  that  body 
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of  code.  In  other  words,  the  procedure  has  direct  access  to  the  set  of 
variables  defined  in  its  hierarchic  ancestors  with  which  that  procedure  was 
compiled.  No  provision  is  made  for  passing  parameters.  (See  Section  4.3.5 
for  generalized  header  information.)  The  string  may  consist  of  any  input 
characters,  btit  may  not  be  used  to  designate  passing  of  arguments.  tTie 
name  must  be  a valid  identifier  and  must  exactly  match  the  field  following 
only  one  oo  somewhere  in  the  same  compilable  se  ^tion  of  CRiSP  source 
data  in  order  to  be  translated  correctly.  Name  is  converted  by  CRISP 
translators  to  a unique  program  label 

CRISP-PDL  identifies  procedure  modules  unlinked  to  by  DO  and  multiple 
DOS  invoking  the  same  procedure  (not  permitted)  in  the  status  report. 

On  execution,  the  ENDTO  or  knoprocgoure  statement  signals  a return  of 
control  back  to  the  invoking  module.  Additional  returns  (or  escapes)  from 
procedures  can  also  be  effected  by  the  use  of  the  exit  statement.  See  EXIT 
in  Section  4.3,13  for  paranormal  exit  information. 

CRISPFLOVV  generates  a one-page  flowchart  as  illustrated  in  Figure 
4.2.2. 1 in  response  to  procedure  module  source  input. 

4.3.25  PROGRAM  Structure 

The  main  program  is  announced  by  the  program  statement.  In  base 
languages  which  require  that  this  program  have  a named  beginning,  the 
program  name  must  follow  the  conventions  of  the  base  language.  Where 
naming  is  not  required  by  the  base  language,  the  name  may  be  ignored  by 
the  translator  (in  such  cases,  however,  the  program  statement  must  usually 
be  the  first  executable  statement). 

The  main  program  module  continues  until  the  ewdprogram  statement; 
statements  past  endprogbam  (compiled  with  the  main  program)  are 
generally  subroutines,  procedures  invoked  by  TO  and  defined  by  to  (or 
procedure)  structures,  or  else  are  data  declarations  or  intermodule  text. 

The  format  is,  therefore,  of  the  form  (see  Section  4.3.5) 

pmvw  [<*fhfc!*>]  [MOD#  dewaj] 

structure 
ENOPROGRAM 

Upon  nmtime  execution  of  gnoprogram,  control  flow  returns  to  the 
system  or  processor  controlling  the  execution  of  the  program,  (For 
example,  batch  FORTRAN  probably  returns  to  the  operating  system  and 
thence  to  the  users  job  centro!  stream.  For  interactive  systems,  such  as 
BASIC,  control  probably  returns  to  the  BASIC  command  mode.) 
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To  control  the  type  of  program  exit  when  a choice  is  available,  two 
directives,  STOP  and  SYSTEM,  are  provided.  STOP  returns  program  control  to 
a supervisory  program  controlling  the  program  being  executed,  such  as  the 
BASIC  processor  mentioned  above*  system  returns  control  back  to  the 
operating  system  and  to  the  user’s  job-control-language  stream, 

STOP  and  SYSTEM  may  only  appear  within  the  confines  of  PROGRAM.,  ,end- 
PROGRAM  statements,  and  may  not  appear  in  subroutines,  macros,  functions, 
or  procedures. 

CRISP-PDL  formats  stop  and  SYSTEM  the  same  as  abort  (Section  4*3*7). 
CRTSPFLOW  generates  the  flowchart  elements  below: 

I I 

( ) ( ) 

(forENDPROGRAMl 

4.3.26  REQUIRE  Statement 

The  REQUIRE  statement  is  of  the  form 


^ SYSTEM  ^ 


REQUIRE  AT  {hnniitj:  statement 


This  causes  the  CRISP  translator  to  extract  and  save  statement  during  the 
first  pass,  i.nd  to  insert  it  during  the  second  pass  into  the  object  code 
immediately  before  the  code  for  that  statement  whose  dcweij  ^decimal 
identifier  is  given.  This  identifier  is  determined  from  the  MOD#  field  of  the 
appropriate  module  header  and  the  .step  number  .dd  within  that  module* 
See  Section  7,2.4  of  Reference  7*2,5  for  further  details. 

4.3.27  RETURN  Statement 

The  RETURN  statement  is  a paranormal  exit  from  a subroutine  or 
FUNCTION  module*  The  listing  format  is  identical  to  EXIT,  except  for  the 
keywords* 

SUBROUTINE  ... 


:< return  [intci^vr] 


ENDSUBROUTINE 
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The  action  of  RETURN  is  similar  to  that  of  exit.  Tf  an  integer  value  is 
specified,  that  value  is  assumed  to  be  assigned  to  the  OUTCOME  flag  (Section 
4.3.23). 

CRISP  translators  then  generate  code  to  make  such  assignments  and 
branch  to  the  ENOSUBROUTINE  (or  ENOFUNCTIOn)  point,  which  redirects 
control  how  hack  to  the  calling  program,  endsubroutine  additionally  resets 
OUTCOME  to  zero  ai  a point  above  the  return  collection  node  if  a RETURN  integer 
has  appeared. 

RETURN  may  appear  at  any  level  of  decision  or  loop  nesting  within  the 
module;  RETURN  may  not,  however,  be  used  to  escape  from  more  than  one 
nested  subroutine  or  function  module  at  a time. 

CRISPFLOW  generates  »'^he  icnntcal  symbol: 


4.3.28  STUB  Identification 

The  STUB  keyword  is  used  only  by  CRISP-PDL  and  CRISPFLOW 
processors  to  identify  procedures,  subroutines,  and  functions  that  represent 
dummy  stnicturcs  to  be  removed  later.  The  format  is  exemplified  by  the 
form 

TO  mtmt: 

STUB 

ENDTO 

CRISP-PDL  marks  the  name  of  the  procedure  as  being  a stub  for  display 
in  the  stub  status  report, 

CRISPFLOW  adds  the  word  '‘stub'*  to  the  upper  right-hnnd  module 
identification  following  the  name  and  preceding  the  date  fields: 

dewoy 
nmne 
STUB 
(Uac  1 
{htt^ 
page of — 
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4.3.29  SUBROUTINE  Structure 

The  subroutine,  invoked  by  the  call  (or  perhaps  CALLx)  statement,  is  the 
code  body  structure  appearing  between  SUBROUTINE -endsubroutine 
statements.  Upon  entry  during  execution,  the  first  line  after  SUBROUTINE  is 
the  first  executed;  upon  reaching  the  ENDSUBBOUTINE  statement,  control 
returns  to  the  calling  program  in  the  normal  fashion. 

Subroutines  are  potentially  separately  compiled  entities.  Local  variables 
defined  within  a subroutine  must  not  be  accessible  to  the  invoking 
program.  Therefore,  provisions  for  passing  arguments  or  parameter  lists  are 
assumed.  Subroutines  may  invoke  subprocedures  by  using  the  do  statement, 
provided  the  invokr  J procedures  are  defined  by  TO  or  PROCEDURE  structures 
in  the  same  compilable  unit.  Subroutines  may  also  call  (or  callx)  other 
subroutines  or  invoke  FUNCTIONS, 


Except  for  the  keywords,  the  listing  structure  of  a subroutine  is  the  same 
as  any  other  module i 


SUBROUTINES  subnamc  (MOO#  f/ftrerd 

structure 

ENDSUBBOUTINE 


See  Section  4.3,5  for  format  and  4,3.27  for  use  of  the  return  statement  to 
produce  paranormal  escape. 


The  subname  contains  the  subroutine  name  and  arguments  passed  to  and 
from  the  subroutine.  Base  language  syntax  applies  to  this  subnome.  If  local 
and  external  subroutine  definitions  must  have  different  syntaxes,  the 
keyword  XSUBROUTINE  may  be  added. 


CRISPFLOW  generates  the  flowchart  format  illustrated  in  Figure 
4.2,2,1,  except  that  RETURN  appears  in  termination  symbols. 


4.3.30  WHEN  Structure 

The  WHEN  structure  is  a means  for  handling  priority  interrupts  for  reab 
time  processes.  The  syntactic  form  is  illustrated  by  its  CRTSP-PDL  listing 
form: 


\ 
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: : {cvenii)  prioriiyi 

: : jttrttcUiwl 

: : {ct:cnt2)  fmorfhj2 

: : .stnwiurc2 


(NORMAL) 

: : siruttfurcn 

. ENDWHEN 

The  CRISP  translator  generates  code  to  connect  and  arm  all  priority 
internipts  for  the  events  listed  at  the  priority  levels  given  (if  permitted)  and 
proceeds  to  execution  of  the  NORMAL  structure,  which  must  be  the  last 
clause.  Interrupts  occurring  during  the  execution  of  *^he  normal  clause  pass 
control  to  the  corresponding  event  in  order  of  priority,  : “^mpletion  of  an 
event  clause,  control  returns  to  the  point  of  interruption.  When  the  normal 
clause  completes  at  ENDWHEN,  all  intermpts  for  the  events  involved  are 
disabled. 

The  event  syntax  is  that  of  the  base  language.  See  Section  4.3.22  for 
further  discussion  of  NORMAL. 

In  order  for  WHEN  structures  to  he  nested  within  other  WHEN  structures 
utilizing,  perhaps,  the  same  internipt  assignments,  it  may  be  necessary  for 
WHEN. . .ENDV/HEN  to  save  and  restore  internipt  vectors  or  such  other 
mechanisms  used  in  the  target  language  to  maintain  proper  control 
correctness  of  program  segments. 

CRISPFLOW  generates  the  following  flowchart  elements  for  the  when 
structure: 
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4.4  User/ Operator  Special  Features 

This  specification  does  not  address  user/operator  interfaces,  procedures, 
or  protocols.  Inasmuch  as  user/operator  I/O  devices  have  been  left 
unspecified,  the  form  and  extent  of  option  selection  is  left  open  for  system- 
dependent  considerations. 

However,  users  are  assumed  to  be  responsible  for  generating  and  editing 
the  CRISP  source  input  programs  prior  to  invocation  of  the  CRISP 
processors  herein  described. 

In  particular,  CRISP  program  modules  within  a file  are  selectively 
processed  by  control  data  given  to  a CRISP  processor  of  this  specification. 
Users  must  first  prepare  alternate  scratch  files  containing  such  selected 
modidef?  U they  wish  to  do  so.  The  capability  to  extract  and  form  such 
scratch  files  is  not  included  in  this  specification  of  CRISP  processors; 
however,  such  a capability  is  not  proscribed  by  this  document 


4.5  Data  Base  Specifications 

CRlSP-PDL  and  CRISP  translators  shall  be  designed  in  such  a way  that 
they  may  share  a program  listing  file  for  display  purposes  (Section  4.3.11)  in 
a future  upgrade,  so  that  target  compiler  error  messages  and  execution 
statistics  can  appear  on  the  cosmetized  program  source  listing. 

All  CRlSP-PDL  report  material  and  CRISP  translator  output  shall  be 
mairUainable  in  compatible  formats  so  as  to  be  useful  as  data  base  elements 
in  applications  programs  developments.  Files  shall  be  maintained  in  the 
formats  specified  by  this  document  All  files  written  for  retention  by  users 
shall  be  named  by  system-dependent  standards  *hat  readily  identify  the  file 
type  (listing,  target  code,  etc.)  and  the  applications  program  to  which  they 
correspond. 


5.  PROGRAMMING  SPECIFICATIONS 

Programming  specifications  are  not  included  in  this  version  of  this 
document. 


e.  TEST  AND  VERIFICATION  SPECIFICATIONS 

Test  and  verification  specifications  are  not  included  in  this  version  of  this 
document. 
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7.  APPENDICES 
7.1  Giodsary 

ANSI.  American  National  Standards  /nsticute. 

Base  language.  The  language  used  in  non-control  statements  in  the  source 
program  processed  by  CRISP.  Normally  the  same  as  or  related  to  the 
target  language, 

CRISP.  Control  Restrictive  /nstnictions  for  Structured  Programming, 

CRISP-FDL,  CRISP  Program  Description  Language. 

CRISPFLOW,  CRISP  iXOWchart  generating  processor. 

Dewey-decimal.  A modulo  identification  scheme  which  concatenates^  using 
a period  separator,  the  current  module  Dewey-decimal  with  the  step 
number  within  that  module  where  a procedure  is  invoked.  The  Dewey- 
decimal  so  formed  becomes  the  procedure  identifier. 

HIPO,  Hierarchic  /nput,  Processing,  and  Output.  A graphical  method  of 
displaying  functional  specifications. 

Module  ender.  One  of  the  keywords  ENDTO,  endprogram,  endprocedure, 
ENDFUNCTION,  ENDSUBROUTINE,  ENDMACRO,  or  %END. 

Module  header.  The  statement  that  introduces  the  definition  of  a 
PROCEDURE,  SUBROUTINE,  FUNCTION,  PROGRAM,  or  MACRO. 

Paranormal  exit.  An  unstmetured  escape  from  a module  or  loop. 

STAGES.  A general  purpo.se  macro  processor  based  on  templa  e matching. 

Target  language.  The  language  that  a CRISP  translator  outputs  in  respoase 
to  source  input.  Normally  the  same  as  the  base  language. 


7.2  References 

This  appendix  lists  documents  containing  explanatory  material  referred 
to  in  other  sections  of  this  SSD. 

,1  Waite,  W,,  *‘The  Mobile  Programming  System  STAGE2/’  Commun. 
ACM,  Vol.  13,  No.  7,  pp.  415-421,  July  1970. 

.2  Waite,  W.,  Imphmcniing  Sojhvare  for  Non-\Uimenc  AppIicatioriSi 
Appendix  A,  Prentice-Hall,  Inc.,  Englewood  Cliffs,  NJ,  1973. 

.3  American  National  Standard  Flowchart  Sijmholji  and  Their  Usage  in 
Information  Processing,  ANSI-X3.5'1970,  .American  National  Standards 
Institute,  Inc.,  NY,  Sept.  1,  1970. 
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.4  Taiisworthe,  R.  C.,  Standardized  Development  of  Computer  Software, 
Part  II,  Appendix  B,  this  text. 

,5  Ibid.,  Part  I,  Chapter  7,  1976. 

7.3  Program  Analysea 

(To  be  supplied  during  prograin  design  phase.) 

7.4  Sharable  Subroutine  tdentification 

(To  be  supplie<l  during  program  design  phase,} 

7.5  Provisions  for  Future  Modification 

(To  be  provided  during  program  design  phase.) 

7.6  Error  Messages  and  Diagnostics 

(To  be  provided  during  program  design  phase,) 

7.7  Detailed  Formats 

7*7.1  Detailed  Control /Response  Message  Formats 

These  formats  are  not  applicable  to  this  impletnentatton-indcpendent 
design,  but  will  become  applicable  in  an  actual  implementation.  Standards 
for  interactive  and  batch-mode  operation  will  be  established  for  each  .such 
application  prior  to  such  implementations. 

7.7.2  Detailed  Input/Output  Formats 

Input  and  output  formats  are  permitted  by  this  specification  to  be 
implementation-dependent  only  when  conformance  to  this  specification 
cannot  be  supporter!  by  the  host  system.  Source  input  formats  shall  be 
compatible  with  the  forms  in  Section  4.3.  Further,  the  cosmetized  reinput 
file  output  by  CRISP-PDL  shall  also  be  compatible  .source  input  for 
CRISPFLOW  and  CRISP  translators. 

The  remainder  of  this  section  covers  output  report  formats  for  the 
CIUSP’PDL  processor  as  described  in  Section  4.2.1.  All  such  outputs 
presume  the  availability  of  a 132-charactcr-per-liue  output  device. 

7 7.2.1  CRISP-PDL  Title  Page  Format 

Figure  7J.2.1.1  illustrxites  the  format  of  the  title  page,  fnformation  on 
this  page  is  taken  from  the  first  records  input  from  the  source  metltum 
when  these  records  are  textual  (not  module  descriptions). 
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the  first  record  is  presvimed  to  he  a document  number  or  other 
identifier^  this  record  labels  each  remaining  page  of  •^he  report  (centered  on 
each  page  except  the  title  page).  The  next  set  of  source  records,  up  to  the 
beginning  of  a module  or  the  # # # signal,  is  copied  directly  onto  the  title 
page.  The  text  signals  # # and  # # # themselves  are  not  printed  on  the 
title  page.  Title  text  may  extend  over  more  than  one  page  if  there  are  too 
many  records  in  the  first  text  block 

Titular  material  occupies  the  rightmost  80  columns  of  the  page,  the 
leftmost  52  being  a CRISP  logo,  shown  in  Figure  7,7.2. 1.2. 

Source  text  records  longer  than  80  characters  will  be  truncated  on  the 
right  (an  error  will  appear  in  such  cases  on  the  monitor  device). 

If  the  first  block  input  from  the  source  medium  is  a module,  the  title 
page  is  left  blank  (except  for  the  logo),  and  a null  (blank)  line  for  the 
document  identifier  appears  on  subsequent  pages  of  the  report. 

7.7.2.2  Table  of  Contents  Listing  Format 

The  table  of  contents  is  a listing  of  intermodule  text  lines  signalled  for 
printing  by  a leading  # -space,  together  with  names  following  module 
header  keywords.  These  are  printed  in  order  of  appearance  and  annotated 
with  page  and  line  numbers  of  occurrence  within  the  CRISP-PDL  listing. 
Each  page  of  the  table  of  contents  contains  a header  with  the  program 
name  {if  any)  and  ‘Table  OF  CONTENTS'*  designation.  Pages  after  the  first  add 
“(CONT.  The  format  is  shown  in  Figure  7.7.2.2.1,  Page  and  line  nvmbers 
may  extend  to  four  characters  each,  right-justified  and  zero-suppressed.  No 
decimal  appears  in  either. 

7.7.2.3  Program  Director)'  Listing  Format 

The  program  directoiy  contains  an  alphabetic-order  listing  of  all  module 
names,  status  for  each,  and  page  and  line  of  occurrence  within  the  CRISP- 
PDL  listing.  The  format  is  shown  in  Figure  7.7.2.3.I.  The  designation 
“{CONT.  )'*  follows  “directory”  on  all  but  the  first  page.  Page  and  line 
number  specifications  are  the  same  as  given  in  7.7,2.2.  The  status  field  is  six 
characters  wide  and  contains  the  followingt 


“unseen” 

Name  appears  after  00  or  call,  but  does  not  appear 
on  header 

“no  con” 

Name  appears  on  header,  but  does  not  appear  after 
a DO  or  CALL 

“STUB” 

Module  designated  the  name  as  a stub 

**  »» 

Otherv^dse 
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ISSUE  DATE 


SOFTWARE  SPECIFlCATipf^  DOCUMENT 
DSN  PROGRAMMING  SYSTEM 
CRISP  PROGRAM  DESCRIPTION  UANGUAGE 
DESIGN  ANALYSIS  PROCESSOR 


PREPARER 


APPROVED, 


CONCURRED, 


DATE 


DATE 


DATE 


JET  PROPULSION  LABORATORY 
CALIFORNIA  INSTITUTE  OF  TECHNOLOGY 
PASADENA,  CALIFORNIA 


Bgure  7.7^.1.1.  Typical  title  page  output  format 
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CCGCCCCC 

CCCGCCCCC 

CCC 

cc 

cc 

GCC 

CCCGCCCCC 

cccccccc 

RRRRRRRR 
RRRRRRRRR 
RH  RRR 

RRRRRRRRR 
RRRRRRRR 
RR  RR 
RR  RR 

RR  RRR 

nil 

11 

II 

II 

II 

II 

II 

IIII 

ssssssss 

sssssssss 

sss 

sssssssss 

ssssssss 

sss 

sssssssss 

ssssssss 

pppppppp 

ppppppppp 

pp  ppp 

ppppppppp 

pppppppp 

pp 

pp 

pp 


JET  PROPULSION  LABORATORY 
HBOO  OAK  GROVE  DRIVE 
PASADENAt  CA,  9110^ 


Figure  7.7.2.1.2,  CRISP-PDL  logo  format 


document  number 


program  name 


TABLE  OF  CONTENTS 


UNE:PAGE 

iine‘,page 

!ine\page 


line 'page 


roman  numeral 
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document  number 


Figure  7.7.2.3.1,  Program  directory  form^ 
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7.7.2.4  Tier  Chart  Listing  Format 

The  tier  chart  lists  module  names  in  program  invocation-tree  {control 
nesting)  order,  along  with  a status  code  followed  by  the  line  and  page  of 
occurrence*  Status  and  occurrence  printing  are  covered  by  7*7.2*3*  Names 
are  indented  as  specified  in  Figure  7.7.2,4,1  to  indicate  the  invocation  level 
of  nesting  within  the  program.  The  main  program  and  all  subroutines, 
functions,  and  block  macros  appear  at  level  1.  Procedures  and  subroutines 
invoked  by  DO  and  CALL  (X)  within  a module  are  listed  below  the  name  of 
that  module,  indented  as  shown. 

Module  names  are  truncated  on  the  right  if  indentation  interferes  with 
status  pririting  (an  error  message  also  appears  on  the  monitor  device). 

“ (COMT. ) " is  added  after  “TIER  CHART"'  on  all  but  the  first  tier  chart  page. 

7.7*2.5  Module  Status  Report  Format 

This  report  contains  a list  of  nances,  statics,  and  locations  of  modules 
having  status  “stub”  and  “unseen.”  The  report  format  appears  in  Figure 
7.7.2.5.I.  “(CONT, )”  appears  on  all  pages  but  the  first.  Page  and  line 
numbers  are  covered  by  7. 7,2,2.  The  fields  nnnn  and  mm  are  zero- 
suppressed,  right-justified,  with  no  decimal, 

“Unseen”  module  names  are  counted  and  listed  only  once,  even  though 
there  may  be  multiple  occurrences  in  the  procedural  listing;  the  page  and 
line  numbers  are,  thus,  only  typical  invocations.  {The  cross-reference 
concordance  contains  all  such  occurrences,  however.) 

7*7.2.6  Cosmetics  and  Indentation  Format  for  CRISP-PDL 

This  section  details  the  output  procedural  listing  format  of  the  CRTSP- 
PDL  structures.  Each  page  of  the  listing  contains  the  document  number, 
program  name,  source  file  name,  and  current  page  number.  Each  line 
begins  with  the  source  file  line  (record)  number,  up  to  four  characters  zero- 
suppressed,  no  decimal,  right-justified,  and  followed  by  two  spaces,  as 
shown  in  Figure  7.7.2.6.I.  The  remaining  126  character  positions  on  the 
line  are  formatted  as  specified  in  Section  4,3.  Column  positions  referred  to 
in  Section  4.3  arc  relative  to  the  first  character  of  this  126-character  format 
(i.e.,  “column  1”  or  “left  margin”  in  Section  4.3  refers  to  character  position 
7)* 

7, 7.2.7  Glossary  and  Cross-Reference  Table  Listing  Format 

The  glossary  and  cross-reference  table  reports  each  identifier  used  in  the 
program  in  lexicographic  order  in  the  format  shown  in  Figure  7.7.2,7,1. 
“<CONT. )”  follows  “glossary”  On  all  but  the  first  page.  The  page  number 
at  the  bottom  is  the  page  number  of  the  current  page  of  the  report.  The 


document  number 


program  nanye 


PROGRAM  TfER  CHART 


NESTING 


STATUS:UNE;PAGF 


program  . . , , 

: module  name  . 

; ; module  name 
: ; module  name 
: module  nan7e  . 
subroutine  name 


s tat  mi  lit\e\page 
s tat  ui;  fine'.pay  e 
s ra  tus:line-pege 
$ ta  t us:  Uneipage 
5 te  t us'nJifiGipage 
s re  t us:iine:p3  ge 


: : : module  name 


s ta  tusi  Uneipage 


roman  numeral 
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docutttetu  fiumbor 


jirogr^m  fw)w 

MODULE  STATUS 

SUMMARY: 

TOTAL  MODULeS  tOENTIFIED:  fuirm 
NON-STUB  MODULES:  nfwn 
STUB -STATUS  MODULES:  r?ntm  mm% 
(OENTIFfEO,  BUT  NOT  LSEN:  rmr?/) 

MODULES  IN  STUB  STATUS; 

nwiitfle  naPftf  finB:/}3n^ 


module  name  iufezpogv 

MODULES  identified  BUT  NOT  PROCESSED: 

ftwdalB  nami} - . * I hi  c:  page 


module  name  hue'.pi^S^ 


ranmn  msmerai 


Figure  7.7.2, 5.1.  The  stub^^status  report 


Rx^ure  7.7.2.6.1,  Page  format  of  procedure  and  infemnodule  text  ISstfngs 
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name  field  extends  to  32  characters  for  each  identifier.  The  type  designator 
begins  immediately  (one  space)  after  the  name  and  is  one  of  the  following: 

(PBOGR.-^^  NAME)  : 

(PROGEDURE  NAME) : 

(SUBROUTINE  NAME): 

{FUNCTION  NAME): 

(MACRO  NAME) : 

(IDENTIFIER): 

Aftei  one  more  space,  the  text  definition,  if  any  appears  in  a corresponding 
LET, , ,8E. , ..statement,  follows.  The  line:  page  designation  Ou  the  name  line 
gives  the  line  and  page  numbers  of  the  LET, . ,be.  , , statement  (this  is  absent 
if  the  identifier  had  no  LET. , .BE. . ,),  Beneath  each  name  line,  the  line: page 
designators  list  all  the  locations  of  appearances  of  that  identifier. 


7,7.2.8.  Statistical  Summary  Format 

The  stati.stieal  summary  format  sketched  in  Figure  7,7. 2.8.1  permits 
printing  of  the  numbers  of  occurrences  of  keywords,  module  source  lines, 
intermodule  text  lines,  histograms  of  module  and  text  block  lengths,  and 
other  statistical  data,  as  specified  below. 


The  statistics  printed  under  “nu?;5BER  of  SOURCE  lines''  are 


IN  MODULES: 


IN  TEXT  BLOCKS: 


NO.  OF  MODULES:  rmriti 

TOTAL  LINES:  nnnn  r«»i% 
COMMENT  STATEMENTS:  nnnn 
UNCOMMENTED  STATEMENTS:  . nnnn  mm% 
MIXED  STATEMENTS:  nrmn  mrn% 
TOTAL  STATEMENTS:  nnm»=  100% 
CONTROL  STATEMENTS:  nnnn  mm% 
NON-CONTROL  STATEMENTS:  rmnri  »ihi% 
AVG  LINES /STATEMENT:  ».n 
AVG  STATEMENTS /MODULE:  nn.n 
AVG  LINES/MODULE:  «n,n 


NO.  OF  BLOCKS:  nnnn 

TOTAL  LINES:  mr;i% 

AVG  LINES /BLOCK:  nrui 


Fields  designated  as  nnnn  or  mm,  above,  represent  numeric  4-  and 
2-character  width  outputs,  right-justified,  zero-suppressed,  no  decimal,^ 
Other  designations  with  decimal  are  as  shown.  Comment  statements  are 
classified  as  any  statement  with  *<*'  in  the  keyword  position.  ^ 


Figure  7^7.2.8,1.  Format  of  the  statiettcal  summary 
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Within  the  “length  statistics^  entry'  are  printed  histograim  of  the 
form 


MODULES 

INTERMODULE  TEXT 

t-5:.r.r 

1-5; 

6-10:  .v.r.v 

11-15:  XXX 

16-20;.r 

16-20:  xr.v 

21-25: 

21-25:.v.v 

26-30: 

26-30;r 

31-36; 

31-35; 

36-40: 

36-40; 

OVER  40; 

OVER  40: 

The  X designators  in  the  histogram  denote  that  characters  will  be  printed, 
nominally  one  for  each  five  lines  counted;  il  fewer  than  five  appear  at  the 
last  place,  “b/’  "c/'  or  “o"  appears.  The  designations  are 

A = 1 
B“2 
c=3 
D~4 
e = 5 

In  computing  text  block  length  statistics,  ##,  ###,  and  #n  signals 
are  not  counted,  but  do  add  to  the  total  source  line  count. 

Under  “keyword,  etc.,'*  the  following  statistics  appear: 

TOTAL  REFERENCES;  rinnn-100% 

MODULE  REFERENCES:  nrum  mm% 

IDENTIFIER  REFERENCES;  rmnn  mm% 

IN  TEXT:  rtrtnn 
IN  STATEMENTS:  »mfm 

KEYWORD  OCCURRENCES;  ri»nn«lQO% 

ABORT  rjfum  . . 


Each  of  the  CRISP  keywords  is  printed  in  alphabetic  order  in  columnar 
format  across  the  page. 

END  OF  SPECIFICATION 


APPENDIX  H 

DEVELOPMENT  PROJECT  NOTEBOOK 
CONTENTS 


The  Project  Notebook,  described  in  outline  form  in  this  appendix,  is 
primarily  an  administrative  and  management  tool,  Pertinent  technical 
information  regarding  software  design,  testing,  operation,  and  use  appears 
principally  in  other  documents  outlined  in  this  set  of  appendices.  Instead, 
the  Project  Notebook  described  herein  provides  a centralized  record  of 
current  and  archived  material  related  to  the  production  of  that  software. 


The  Project  Notebook  is  an  informal,  working-level  document: 
handwritten  notes,  typewritten  memos,  etc.  The  arrangement  of  material 
suggested  below  ranges  through  the  most  useful  project  management 
information,  in  terms  of  aiding  the  project  manager  in  his  function.  Figure 
IM  is  a top-level  view  of  the  notebook  organization. 


The  primary  purpose  of  the  notebook  is  visibility  into  the  current 
development  status.  However,  some  of  the  items  inciudcrl  in  it  (c.g.,  the 
work  breakdown  structure)  are  more  directly  related  to  estimations  of 
manpower,  resources,  and  schedules;  others  (c.g,,  memos,  minutes,  decision 
log)  record  data  that  may  be  needed  for  reference  later  in  the  project;  still 
others  (c.g.,  change  control  log,  standards  waivers)  are  project  control 
mechanisms. 


At  project  completion,  the  archived  material  serves  as  a means  for 
assessing  overall  productivity  figures,  costs,  and  the  utilization  of  resources; 
it  also  provides  useful  information  that  can  guide  the  formation  of  better 
mcthodolog)'  standard-^  and  more  accurate  scheduling  and  costing  methods, 


Figure  H-1,  Suggested  organization  of  the  Development  Project  Notebook 
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In  large  projects*  the  notebook  may  well  require  several  volumes, 
perhaps  one  topic  below  for  each.  In.  smaller  projects*  a loose-leaf  hiiider 
with  index-tabbed  separators  may  suffice. 

If  facilities  and  resources  are  available,  much  of  the  material  may  he  kept 
and  maintained  in  computer  files  (e.g,,  the  tier  chart  and  work  breakdown 
structure).  In  any  case,  the  material  must  be  conveniently  at  hand  for 
viewability  on  demand  by  the  project  manager  or  others*  and  must  record 
the  information  in  an  easily  usable  form. 
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DEVELOPMENT  PROJECT  NOTEBOOK 
Suggesled  Contents 


FRONT  MATTER 


Title  Page»  Provide  a title  page  containing  (l)  project  identification 
number;  l2)  program,  project,  subsyi;tem,  and  system  titles;  (3)  PROJECT 
NOTEBOOK;  and  (4)  name  and  organization  of  custodian. 

Directory.  List  the  sections  of  the  Project  Notebook  by  volume  number  (or 
file  identifier).  This  directory  is  probably  not  necessary  if  the  topics  all  fit  in 
one  notebook  (or  file  drawer)  with  appropriately  tabbed  indices. 


CONTENTS  OF  PROJECT  NOTEBOOK 


1.  ORGANIZATION  AND  RESOURCES 

Provide  an  organizaton  chart  and  role  statements  as  needed.  Identify  the 
manpower,  dollars,  and  other  resources  available,  and  those  needed  to 
complete  the  development.  Display  a profile  of  these  resources  as  a 
function  of  time. 

2.  SCHEDULE 

2.1  Current  Schedule 

Provide  a current  high-level  “master ' schedule  to  show  the  committed 
baseline,  controlled  milestones  (e.g.,  project  review  dates),  and  supporting 
major  achievements  during  the  development.  Maintain  current  lower-level 
schedules  keyed  to  work  breakdown  structure  tasks  identified  and  described 
in  Section  4,  below.  Date  each  page  of  the  schedule.  For  each  line  item, 
show  start  of  work  and  the  period{s)  thereafter  until  milestone  achievement 
Distinguish  unachieved  from  achieved  milestones.  For  example,  designate 
original  milestones  as  unfilled  deltas,  to  be  filled  in  when  achieved. 
Distinguish  slipped  milestones,  say,  as  inverted  deltas  on  the  same  schedule 
line.  Identify  work  periods  as,  for  example,  horizontal  parallel  lines  from 
start  of  v'ork  (broken,  if  there  are  periods  of  inactivity)  to  the  delta.  Darken 
between  tjtesc  lines  to  indicate  progress. 
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2. ?  Significant  Notes 

Record  reasons  for  current  slippages  (unless  contained  in  progress  reports 
archived  in  Section  3,  below),  assumed  contingencies,  and  other  schedule- 
related  matters  as  needed  to  indicate  the  current  plan  or  to  facilitate 
project  operations* 

2.3  Schedule  and  Note  Archives 

Retain  outdated  project  schedules  and  schedule  notes  for  reference 
needed  later  during  this  project,  as  well  as  for  historical  purposes* 

3.  PROGRESS/STATUS  REPORTS 

Imert  the  regular  progress  reports  written  by  project  members  to  project 
management,  or  by  project  management  to  higher  management,  the 
customer,  or  other  organizations.  Retain  past  reports  for  later  reference 
during  this  project,  as  well  as  for  historical  purposes. 

Such  status  reports  should  record  (l)  significant  milestones  achieved;  (2) 
change  in  development  plan  and  rationale  for  change;  (3)  resource 
expenditures;  (4)  activity;  (5)  forecast  of  activities;  (6)  computer  utilization 
figures,  such  as  computation  costs,  numbers  of  debugging  nms,  etc.;  (7) 
progress  monitors,  such  as  percentage  of  total  milestones  achieved,  pages  of 
documentation,  lines  of  code,  etc*,  generated;  (s)  problems  and  potential 
problems;  (9)  other  information  “for  the  record*” 

4.  WORK  BREAKDOWN  STRUCTURE 

The  work  breakdown  structure  (WBS)  contains  necessary  information  to 
provide  visibility  and  control,  using  quantifiable  relationships  and 
interdependencies  of  resources,  schedule,  and  technical  performances. 

4.1  Task  Hierarchy 

Organize  and  display  the  software  development  effort  as  a tree  hierarchy 
of  work  packages  (tasks)  that  are  significant,  finite,  and  manageable,  with 
quantifiable  inputs,  outputs,  resources,  schedules,  and  assigned  responsibili- 
ties. Each  task  should  ideally  require  the  same  effort. 

4.2  Task  Descriptions 

Describe  each  task  in  the  WBS  in  a uniform  format.  Include,  as  a 
minimum,  the  following:  (l)  date  the  description  form  was  completed;  (2) 
revision  number  of  the  description;  (3)  WBS  task  title  and  Dewey-decimal 
identifier  in  the  WBS  hierarchy;  (4)  responsible  individual;  (a)  duration, 
planned  and  actual;  (6)  task  description,  or  brief  identification  of  what  the 
task  is  intended  to  accomplish,  what  the  task  is  part  of,  etc*;  (7)  schedule 
with  start  and  finish  dates,  including  appropriate  milestones  for  task 
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elements;  (S)  task  budget  or  time-phased  manpower  by  skills  categories 
necessary  for  task  accomplishment,  including  supervision,  design,  coding, 
testing,  documentation,  and  support  services;  (9)  task  scope,  or  estimate  ol 
lines  of  code,  number  of  flowcharts  and  narrative,  etc.;  (lO)  inputs  required, 
such  as  documentation,  other  task  outputs,  hardware,  or  other  resources 
that  are  necessary  to  accomplish  task,  including  need  dates  for  each;  (ll) 
task  outputs,  interim  and  final,  such  as  reports,  supporting  documentation, 
design  documentation,  operating  code,  listings,  etc.,  including  output  dates 
for  each;  and  (l2)  task  interfaces,  such  as  common  software,  interchange- 
able modules,  or  other  relationships  between  this  and  other  tasks* 

4.3  WBS  Integration 

Display  task  interdependencies  in  some  suitable  way,  such  as  PERT  or 
schedule  networks  (cost  or  time).  Identify  critical-path  tasks  and  float  times* 

4.4  WBS  Archives 

Retain  previous  WFx-v  task  descriptions,  etc.,  after  updates  for  historical 
purposes, 


5.  DEVELOPMENT  MONITORS 

5.1  Tier  Chart 

If  not  contained  in  Section  4,  above,  maintain  a current  tier  chart  of  the 
developing  program.  Identify  modules  by  category  lor  statu.s  reporting. 
Such  categories  might  include:  (l)  module  approved  into  project  change 
control;  (2}  module  completed,  but  pending  project  approval  into  internal 
change  control,  or  being  reworked  for  reapproval;  (3)  module  exists  in 
preliminary  or  look-ahead  form  in  SDL;  and  (4)  module  identified  in 
program  tree  hut  not  yet  seen  by  SDL.  These  categories  apply  to  design 
items,  documentation  items,  coding,  and  testing. 

5.2  Production  Log 

Maintain  a log  or  set  of  logs  that  summarize  the  current  production 
status  and  disposition  of  resources  and  materials*  This  part  of  the  notebook 
should  record  (l)  the  traffic  and  ciLStoclianship  of  documentation  items, 
data,  program  tapes,  and  disk  files;  (2)  resources  expended  (manpower,  CPU 
usage,  number  of  debugging  runs,  etc);  (3)  implementation  statLstics 
(numbers  of  lines  of  code  entered,  altered,  etc  );  and  (4)  tests  conducted. 


Appendix  H 379 


5.3  Rate  Charts 

Maintain  graphs  of  cumulative  activities  as  a function  of  project  day, 
suitable  for  forecasting  future  accomplishments,  identifying  trouble  spots, 
calibrating  productivity,  etc.  Such  plots  should  display  cumulative 
milestones,  modules  completed,  number  of  anomalies  discovered  and 
repaired,  schedule  days,  arid  manpower. 

6.  MINUTES  OP  PROJECT  MEETINGS 

6.1  Project  Meeting  Notes 

Record  the  minutes  of  all  project  meetings.  Give  the  date,  attendance, 
agenda,  and  pertinent  facts  or  issues  discussed.  Identify  action  items  and 
responsibilities. 

6.2  Action  Item  Log 

Maintain  a current  list  of  all  action  items,  the  responsible  parties, 
assigned  compliance  datas,  and  disposition. 

7.  PROJECT  BULLETINS 

Retain  all  project  bulletins  and  other  pertinent  memoranda  needed  for 
project  reference  or  historical  purposes,  issued  within  or  received  from 
sources  external  to  the  project. 

8.  OECISfON  LOG 

Record  project  decisions  that  bear  on  later  project  plans  and  for 
historical  purposes.  Decisions  which  may  be  useful  to  or  influence  program 
sustaining  and  maintenance  may  he  recorded  here  for  convenience; 
however,  these  latter  decisions  should  als'o  be  inserted  eventually  into 
Appendix  7.10  of  the  SSD. 

9.  ANOMALY  SYSTEM 
9,1  Anomaly  Status  Log 

Maintain  a llit  of  all  reported  anomalies  as  described  in  9.3,  below.  Give 
for  each:  (l)  anomaly  number;  (2)  short  problem  description;  (3)  system/ 
subsystem /program  identifier;  (4)  discover)^  date;  (5)  priority  catcgoiy^;  (6) 
'S;ssignod  responsibility;  (?)  required  closure  date;  (8)  actual  closure  date;  (9) 
disposition  method  anrl  action. 

Display  graphs  of  the  number  of  anomalies  di.scovered  and  number  of 
anomalies  cleared  versus  date  or  usr.ge  time  (either  here  or  in  Section  5.3), 
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9.2  Anomaly  Descriptions 

Retain  copies  of  alJ  individual  anomaly  forms  summarized  in  9.1^  above, 
in  this  section. 

9.3  Anomaly  Definition 

Identify  or  give  a reference  to  criteria  for  anomaly  detection  and 
reporting  during  the  production  phase  (including  acceptance  testitig). 
Define  priority  categories,  such  as;  (A)  removal  of  anomaly  is  critical  for 
usage  of  the  soft\\are  as  required;  (B)  anomaly  degrades  performance  or 
increases  operational  risks;  and  (C)  anomaly  does  not  prevent  softu^are  from 
being  used  successfully,  but  is  undesirable  in  that  it  requires  some  user/ 
operator  reorientation  or  work-around  procedure. 

9.4  Anomaly  Reporting  System 

Describe  (or  reference)  the  anomaly  reporting  system,  including  roles  of 
individuals  involved  with  supervision,  testing,  correctiofi,  QA,  etc.  Also, 
describe  any  pertinent  interfaces  and  procedures  that  are  used. 

10.  INTERNAL  CHANGE  CONTROL  LOG 

10.1  Change  Status  Log 

Maintain  u summuiy  list  of  deliverable  items  (modules,  documentation, 
code,  etc,)  in  conjunction  with  the  tier  chart  in  Section  5,  above,  or  the 
VVBS  in  Section  4,  above,  that  records  the  traffic  during  development,  so  as 
to  keep  track  ot  development  items  among  subcontractors,  team  members, 
QA,  etc. 

10.2  Change  Control  Log 

Retain  copies  of  all  development  change-request/change-order  forms  in 
this  section.  Such  request  forms  should  contain  (l)  name  of  requester;  (2) 
date;  (3)  systcin/suhsystem/program/  module  identifier;  (4)  reason  for 
proposed  change;  (5)  description  of  proposed  change;  (6)  seriousness;  (7) 
method  of  change;  (S)  estimated  resources  required;  (9)  analysis  and 
remarks;  (lO)  availability  of  required  resources;  (]  l)  constraints  on 
resources;  (12)  related  changes  requested,  implemented,  or  to  come;  (l3) 
need  date;  (14)  priority;  (lo)  approval  or  denial  and  reason. 

10.3  Change  Control  System 

Identify  or  give  a reference  to  criteria  for  change  control  action  during 
the  software  dc'velopment  phase.  Describe  (or  reference)  policies  and 
procedures  that  effect  such  changes,  and  include  ’■oles  and  interfaces  of 
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individuals  involved  with  supervision,  design,  coding,  testing,  documenta- 
tion, etc, 

11.  STANDARDS  WAIVERS 

11.1  Standards  Waiver  Policy  and  Procedure 

Record  (or  reference)  the  policies  and  procedures  regarding  waiving  of 
standard  practices  during  software  development,  including  requhv'd  levels 
of  authorization  for  the  various  standards  imposed, 

11.2  Standard  Waiver  Log 

Retain  copies  of  all  Standards  Waiver  Request  forms  in  this  section.  Each 
waiver  request  should  contain  (l)  name  of  requester;  (2)  system/siibsystem/ 
program /module  name;  (3}  date;  (4)  standard  to  be  waived;  (o)  scope  of 
waiver;  (6)  reason  for  request;  (?)  description  of  alternative  to  standard  and 
justification  for  use;  (S)  approval  or  denial 
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APPENDIX  I 

OPERATIONS  MANUAL  CONTENTS 


This  appendix  contains  an  outline  of  topics  typically  considered  for 
incliLsion  in  a Software  Operations  Manual  (SOMX  The  items  listed  are  not 
exhaustive,  nor  are  all  cf  those  given  necessarily  applicable  to  a particular 
given  operator  guide.  Rather,  the  topics  herein  contained  arc  those  that 
should  be  considered  as  candidates  for  inclusion  in  such  a guide. 

As  in  all  documentation,  the  preparer  must  address  his  n^uterial  toward  a 
set  of  intended  readers*.  For  operational  iLse,  this  orientation  should 
primarily  he  toward  the  operator  during  an  actual  nm  of  the  program. 
Secondarily,  the  manual  should  serve  as  a training  base  for  operators. 
Finally,  it  should  serve  as  an  information  medium  to  those  who  would  read 
the  manual  to  survey  the  appropriateness  and  adequacy  of  tlic  program  for 
subsequent  operational  activity.  The  outline  below  is  an  attempt  at 
providing  a logically  and  hierarchically  arranged  checklist. 

This  text  has  repeatedly  recommended  that  manuals  be  written  at  least  in 
a skeletal  form  from  the  top  down  {in  detail  hierarchy)  concurrently  with 
the  writing  of  the  SSD  hierarchy  and  with  the  construction  of  the  program, 
so  as  to  provide  timely  information  among  developers,  to  permit  the 
operator  manual  to  be  tested  concurrently  with  the  program,  and  to  avoid 
last-minute  efforts  to  complete  the  documentation  prior  to  software 
deliver)^  The  emphasis  in  writing  the  operator  manual  is  on  providing 
complete  and  effective  information  for  exercising  all  of  the  options  and 
operational  functions  of  the  program.  The  timely  gathering  of  information 
and  writing  of  technical  material  for  the  iminual,  however,  must  not  be  put 
in  series  with  the  formal,  more  clerical  aspects  (such  as  typing  and 
reproduction)  of  a documentation  activity. 

As  the  program  construction  proceeds  in  a top-down  manner,  operational 
information  in  greater  and  greater  detail  typically  becomes  available.  If 
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compiled  and  written  into  the  guide  during  this  time,  the  information  level 
will  tend  to  aid  in  assessing  whether  the  emerging  program  falls  within  its 
operational  requirements  implemented  so  far, 

Figure  f-1  is  a top-level  view  of  the  suggested  document  organization; 
greater  hierarchic  detail  is  provided  in  the  written  outline  that  follows.  This 
outline  contains  guidelines  after  each  topical  heading  for  the  type  of 
material  to  be  inserted  at  that  point,  fn  full,  the  topics  constitute  Class  A 
detail 

As  presented  here,  the  operator  is  not  assumed  to  be  the  user  of  the 
program;  therefore,  there  are  no  sections  devoted  to  applications.  When 
operations  personnel  are  intended  to  perform  some  of  the  functions  of 
users,  the  topical  outline  in  Appendix  F can  serve  as  a guide  for  selecting 
such  material  as  appropriate  for  inclusion  in  the  manual 

The  operator  typically  receives  requests,  instructions,  data  and 
parameters  for  running  the  program  and  for  performing  other  services 
having  to  do  with  interfacing  the  program  capabilities  with  applications 
and  system-level  personnel  This  often  includes  such  things  as  scheduling  of 
ruus  and  resources,  maintenance  of  tapes  and  files,  loading  of  program 
elements  and  data,  policing  authorized  use  of  the  program  and  data, 
monitoring  execution,  recording  performance  characteristics  (e.g.,  costs, 
number  of  users,  anomalies,  etc,),  recognizing  and  reacting  to  alarms,  and 
routing  of  the  program  outputs. 

Tn  orienting  the  material  toward  the  intended  operators,  use  the 
“robotic”  instructional  approach.  Make  the  manual  “stand-alone, 
extracting  nccessaiy^  operational  procedures  from  existing  references  if 
needed  to  guarantee  stand-alone  operation.  Other  references,  supporting 
narrative,  examples,  etc,,  may  be  included  as  necessary,  and  are  encouraged. 

In  generating  an  SOM  to  the  outline  attached,  arrange  material  global  to 
a .set  of  siiV>section.s  under  the  introductory^  siiperheading  fer  tliose 
subsections.  Use  short  instructions  with  specific  examples  that  actually  run. 
If  syntactic  variables  are  used  to  illastratc  a generalized  form  of  input  or 
output,  clearly  display  and  explain  the  syntactic  convention  and  the  valid 
substitution  values  of  each  syntactic  variable,  Then  give  valid  examples  on 
the  use  of  the  form  being  described. 

Keep  the  manual  as  short  as  possible  while  making  it  say  what  needs  to 
be  said.  Strive  for  clarity  and  completeness  in  exposing  the  material,  but 
tempered  by  conciseness. 

Sources  for  the  material  in  this  appendix  are  [5]  and  [44]  through  [46l. 


SOM 


Figure  1-1,  Graphical  outline  of  the  SOM 
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OPERATIONS  MANUAL 
Detailed  Table  of  Contents 


FRONT  MATTER 


Tiilc  Provide  a title  pas;c  containing  (l)  docninent  luimhcr;  (2) 

program,  .suijsystem.  and  system  titles;  (.3)  SOP'l'W.'VUE  OPERATIONS 
MANUAI^:  U)  puhlk.\  Uou  date;  (5)  author  and  nuuiiu^emont  authority 
si^^natures.  :ls  appiopriate,  and  (6)  pti[>lishiui'  orj^anization*  Signature  or 
puf)llcatiou  approva!  should  he  supplied  only  at  SSD  completion.  The  date 
reflects  the  time  of  latest  change  to  any  item  in  tlie  maunal. 

Abstract.  Give  a brief  ah.struct  that  suiiumui'/e.s  the  purpose  and  usage  oi 
this  iiKumah 

Change  Cmitroi  Information.  Provide  a statement  that  specifics  the 
current  level  of  cluinge  control  authority,  and  describe  procedures  for 
submitting  change  requests  and  reporting  anomalies. 

Distrihntton  Information.  Provide  information  that  tells  how  copies  of  this 
document  may  he  obtained. 

Table  of  ConteiU.s,  Provide  a detailed  table  of  contents  for  tlic  manual, 
which  lists  section  number,  title,  aud  page  of  every  item  with  a heading. 
('Phis  is  probably  the  lust-supplied  item  in  generating  the  manual.) 


TEXT  OF  MANUAL 


1.  INTRODUCTION 

1,1  General  Description  of  the  Manual  and  Its  Use 

Ocsv.rilm  the  purpose  of  the  manual  and  the  salient  features  involved 
with  its  oj>eration.  Summarize  the  specific  uses  of  the  nuimial,  to  whom  it 
is  addressed,  why  it  is  necessary,  how  and  when  it  is  intended  to  bo  used, 
the  nccessar}'  level  of  operator  expertise,  and,  finally,  wtierc  one  may  go  to 
obtain  additional  relevant  material. 

Also  appropriate  in  this  introduction  are  backgr(>und  information, 
history,  relationships  to  other  programs  or  system,  and  other  operational 
matters. 
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1.2  OHentation  and  Scope 

Sniiiiuari/c'  the  extent  of  the  mutenal  i;iven,  the  ratige  of  ap|)l  feat  ion  of 
the  |imgnim.  tiie  operatumal  personnel  rei|uire(l,  and  major  constraints  in 
opc' rating  flic  program. 

1.3  Applicable  Documents 

Identify  all  documents,  controllijig  nr  informational,  which  apply  to. 
regulate,  or  extend  the  operation  of  the  }>mgram.  Include  a In ief  statement 
ol  the  content  o!  c:\cU  doeninent,  its  type  (e,g.,  SSO\  and  purpose. 

1.4  Operational  Overview 

Introdnee  the  operational  emdronment.  the  jirogram  fniu'tion,  and  the 
type  atui  eonteiU  of  data  input.  |>rocessed.  generated,  or  transmitted. 
Describe  the  operator  roie  witii  respect  to  usage  of  the  program.  Ideiitifv 
the  salient  eliaraeteristics  of  the  program,  such  as:  (l)  real-time,  interactive 
or  batch;  (2)  computational  or  data  manipulative:  (3)  developmental  or 
oj>erational.  Identity  the  general  system  or  subsystem  environment 
(hardwan'  and  software)  in  which  the  program  operates  (a  block  diagram  or 
data-How  diagram  is  nsetnl  here).  I ,ea\  e details,  however,  to  ensuing 
sections  of  the?  manual. 

1.5  Guide  to  the  Use  o(  the  Manual 

I'Aplain  lunv  tin’s  guide  is  to  be  nstnl  in  o[ierating  the  program. 


2.  STANDARDS  AND  CONVENTIONS 

'rhis  section  describes  statirlards  imposed  on  or  bv  the  operating 
orgaui/ation.  and  conventioK.s  (e.g.,  notations  and  tcrininoIogxO  applied  in 
the  manual. 

2.1  Operations  Organization  Standards 

Identify  or  reference  applicable  existing  organizational  standard 
o|ierating  proianiures.  stale  any  exceptions  to  these  standards  necessitated 
by  operational  considerations,  and  provide  any  special  standards  required 
for  effet'l  ive  operation  of  the  program. 


2.2  User  Interface  Standards 

Identity  (>r  reference  applicable  existing  pro(‘odurat  or  liaison  standards 
pertaining  to  the  nser/operations  interface,  state  any  exceptions  to  these 
standards  negotiated  as  required  for  usage  or  operation,  and  provide  anv 
special  standards  required  for  operators  to  interface  properly  with  users. 
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2.3  System  Standards 

Identify  or  reference  applicable  existing  system  staiidards  relative  to 
operational  interfaces,  state  any  exceptions  to  these  standards,  and  describe 
ajiy  special  standards  pertaining  to  the  system. 


2*4  Manual  Conventions 

Define  notations,  terms,  and  other  conventions  or  assumptions  used 
generally  throughout  the  manuah  Inciiide  such  items  as  ways  of 
distinguishing  literal  fields  from  syntactic  variables  in  descriptions  of 
operator  input  and  output  formats,  non-standard  mathematical  usage, 
special  acronyms,  etc. 

3*  OPERATIONAL  ENVIRONMENT  AND  INTERFACES 

This  section  descrihas  the  operational  aspects  of  the  program  that 
highlights  man  (operator)/ inachine/system /software  interfaces.  This  section 
is  not  procedural  hut  environmental. 


3.1  Operational  Data  Flow 

Describe  the  data  flow  from  nser(s)  to  operator(s),  through  the  system 
atul  the  program,  and  Inick  to  the  user(s).  Describe  the  role  of  operators  in 
effecting  this  flow.  Identify  operational  interfaces  with  users,  the  system, 
and  libnuy  and  support  facilities. 


3.2  Operational  Environment 

Introduce  the  general  environment  within  which  operators  interface  with 
the  users,  the  system,  other  soft^vare,  and  with  the  program.  This  section 
should  focus  on  the  operational  environment  in  both  static  and  dynamic 
terms.  The  static  portion  of  the  environment  is  defined  by  the  relationships 
between  the  program  and  its  interfacing  with  the  operator,  the  system  in 
which  it  is  imbedded,  and,  perhaps,  other  systems  with  which  it 
communicates.  Data  flow  and  operational  inodes  describing  system/ 
subiystein/operator  interactions  and  sequences  define  the  dynamic 
environment. 

Identify  (l)  interfaces  among  operators  (if  any);  (2)  the  location  of 
operators;  (3)  the  sources  of  operational  data;  (4)  the  media  used  by 
operators  to  control  execution,  input  data,  and  receive  output;  (5)  manual 
tasks,  etc.  Describe  operational  interfaces  with  management,  if  appropriate. 
Defer  operational  features  and  procedures,  specific  formats,  units,  etc., 
until  later  sections. 
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3.3  User  Interfaces 

klentify  luifl  describe  the  interfaces  between  operational  environment  and 
the  program  user  communitv.  Discuss,  as  appropriate,  forms,  interfacing 
procedures,  oflline  storage  media,  data  input  methods,  modes  of  deliver)^  of 
output  to  users,  maiuial  tasks,  etc.  Identify  those  items  that  are  unique  to 
tliis  program  and  not  covered  by  an  overall  system  description  or  governing 
document  (if  this  manual  is  not  to  be  self-contained).  Defer  urer 
procedures,  formats,  units,  etc.,  to  the  user  manual  (.Appendi.v  F).  unless 
user  and  operational  guides  are  combined  in  one  inanuaL 


3.4  System  Interfaces 

Identify  and  describe  interfaces  between  the  operational  environment  and 
the  hardware  and  software  svsteins.  Discuss  data  and  control  input  media 
and  devices,  output  devices,  online  imd  offline  mass  storage  media,  special 
devices,  system  software  interfaces,  system  software  sendees,  etc.  Identify 
protocols  with  systems-levcl  personnel  reqviired  for  operations,  such  as 
private  file  assignments,  assignment  of  job  ctxles,  billing,  etc..  Init  leave 
procedures  for  Section  5.  V.  1. 

3.5  Data  Base  and  Library  Interfaces 

3.5.1  Data  Base  Intcrfuces 

Describe  all  data  fdes  in  the  data  Ixise  that  are  referenced,  supported,  or 
kept  current  by  the  program,  insofar  as  these  are  visible  to  the  opcrator(s) 
of  the  program.  Include  the  name  and  purpose  of  each  such  file,  but  defer 
detailed  formats  to  ai^  appropriate  appendix  (if  these  are  ticccssary  for 
operation).  If  there  arc  oflline  or  manually  maintained  parts  of  the  data 
base  that  interface  with  program  operations,  describe  these  elements. 

3.5.2  Library  Interfaces 

Describe  any  appropriate  operator  interactions  or  interfaces  with 
document  libraries,  software  (program,  subprogram)  libraries,  or  offline 
storage  libraries.  Reference  source  documents  for  data  preparation  and 
editing  aids,  output  data  monitors  and  diagnostic  aids,  etc.,  as  applicable  to 
operations. 

4.  OPERATIONAL  FEATURES 

Thi.s  entire  .section  documents  the  end-to-end  operational  characteristics 
of  the  program  to  a level  of  detail  required  for  stand-alone  iLsage  of  the 
manual.  This  section  should  describe  each  of  the  operator  functions  and 
options  fnllv,  giving  examples  of  each,  annotated  and  explained.  Usage  of 
graphic  material  in  explanations  is  encouraged. 
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4.1  Operaffonal  Overview  and  Capabilitree 

lntTOf*iice  tlie  cict ailed  operational  functional  charactcristicj;  to  l)0 
fliscu,s\sed  in  the  other  sulisoctions  of  thi<^  section  l)V  giving  an  ovcrxaYnv  of 
0|K'rator  functions.  operatioJial  concerns  ajui  activities,  and  program 
operational  cluiracterist ics.  'lypica!  coverage  at  this  point  might  address  Hie 
sti'ucture,  I/O  and  data  flow.  o|ierational  categories,  modes  of  operations, 
security/protcction  measures,  options,  etc,,  as  viewed  by  the  operator(s). 
Use  graplhes  to  aid  reader  coin[)rcliension. 


4.2  Inputs,  Operations,  and  Outputs 

Descn'he  eucli  of  the  features  of  tlie  |>rogram,  as  visiliie  to  or  of  interest 
to,  tlie  opcrator(s);  suf^ply  sudicient  detail  tliat  the  operator(s)  may  apply 
tlie  procedures  in  Section  5.  (Pertinent  input,  operations,  and  output 
cfiaracteristics  will  normally  he  integrated  together  in  a narrative  fashion, 
feature  by  feature.  However,  the  outline  below  is  segmented  into  Miroe 
se[)arate  siil^seetions  so  as  to  delineate  specific  items  to  bo  considered  for 
discussion.) 

4.2.1  Operator  Input  Cliaraeterisiics 

Define  the  reqtitreinonls  of  receiving  and  j>roce.ssing  us*er  requests,  input 
data,  parameters,  and  controls.  4V[)ical  considerations  are  (l)  purpose  or 
conditions.  e,g.,  to  make  needed  revisions  to  data  base:  (2^  frequenev,  e.g.. 
periodically,  randomly,  or  as  a fnnetion  of  an  operational  situation;  (3) 
origin  of  request,  e.g,.  network  operations,  program  office,  etc.:  (4)  mccliiiin. 
e.g.,  punched  card,  mamial  keyboard,  magnetic  tape;  (5)  restrictions,  e.g., 
amount  of  data,  priority,  use  autliorization,  secunty  limitations;  (fl)  quality 
control,  e.g..  need  for  checking  reasonablene.ss  of  input  data,  etc.:  (7) 
disposition,  e.g,,  requirements  for  retention,  return,  release,  or  distrifmtion 
of  inj>nt  data  received. 

4. 2.1. 1 Irpiit  Format 

Provide  tlie  layout  forms  and  syntax  of  op<;rator  inputs  as  ncce.ssarv. 
Include  a descripUoii  of  each  entry,  with  adequate  grammatical  rules  and 
conventions  used  in  eacli  case.  I3istinguish  literal  injMit  from  syntactic 
variable  identifiers.  Typical  considerations  include  (l)  length,  as  characters/ 
line  or  cliaraetcrs/item:  (2^  lonnat,  as.  for  c.xan)[3le,  left-justified  froc-form 
with  spa(‘cs  fietween  items;  (3)  labels,  tags,  or  idenliners;  (4)  sequence,  or 
the  oivler  nl  placement  ot  items  in  tlie  input;  (5)  punctuation,  or  use  of 
spacing  and  symbols  to  denote  .start  and  end  of  input,  of  lines,  of  data 
groups,  ol  items,  etc.:  (6)  rules  governing  tlie  use  of  groups  of  particular 
characters  or  eoinbiruitions  of  parameters  in  an  Input:  (?)  the  vocabulary  of 
aliowalde  comfiinations  or  code.s  that  inu^t  he  used  to  identify  or  conqjosc 
input  items;  (8)  units  and  conversion  (actors:  (9)  0[3tional  elements  and 
repeated  ejoinents;  (lO)  controls,  sucli  as  [leaders  or  trailers. 
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4.2. 1*2  Sample  Inputs 

Provide  specimens  of  each  type  of  complete  input  form  used  by  tlie 
operator.  Such  specimens  should  include,  as  applicable:  (l)  control  or  other 
lieader  information  denoting  class  or  type*  date  and  time  origin,  by  the 
program;  (3)  trailer,  denoting  the  end  of  input  and  other  control  data;  (4) 
indication  of  omissions,  i.e*.  classes  or  types  of  data  that  may  be  onutted,  or 
are  optioiud;  (5)  indication  of  repeated  data,  i e.,  classes  or  types  of  data 
that  may  be  repeated,  and  the  ox'tcnt  of  such  repetition, 

4.2*2  Operalional  Cliaraetorislics 

Detail  the  operational  cliaracteristics  of  the  program,  and  identify  inputs, 
controls,  and  outputs  associated  with  each.  1'ypical  co\^erage  may  address 
requirements  to  monihir  indicatois,  devices,  etc.,  and  to  interact  with  the 
program,  s[)ccial  devices,  other  operators,  users,  cf  a I. 

4.2.3  Output  Characteristics 

Describe  each  of  the  output  forms  or  other  program  responses  to  the 
operator  in  sufficient  detail  for  his  effective  interpretation  in  the  stated 
situation.  Typical  considerations  include  (l)  n.se,  e,g..  by  whom  and  for 
what  purposes;  (2)  frequency,  e.g.,  weekly*  periodically,  or  on  demand;  (3) 
variations,  e.g.*  modifications  that  may  appear  on  the  l>asie  output;  {4} 
destination,  e.g.,  which  users  or  work  area:  (5)  medium,  e.g.*  printout 
punched  cards,  CRT  display;  (fi)  quality  control,  e.g*.  requirements  for 
identific;ition.  checks  for  reasonablene.ss\  authorization  to  edit  or  correct 
errors;  (7)  di.stribution,  e.g,,  requirements  for  .ctention  or  rclca.se, 
distribution,  transini.ssion,  priority,  security  handling,  and  privacy 
considerations. 

4*2.3. 1 Output  Formats 

Provide  a layout  of  each  operator-pertinent  output,  with  explanaloiy^ 
material  keyed  to  the  particular  part.s  of  the  format  illustrated.  Include  U) 
header,  e.g..  title,  identification,  date,  number  of  output  parts,  etc.;  (2) 
body,  e.g.,  information  tliat  appears  in  the  }>odv  or  text  of  the  output, 
columnar  headings  in  tabular  displays,  and  record  layouts  in  machine 
readable  outputs,  noting  wliich  itein.s  may  be  omitted  or  repeated;  (3)  units 
and  conversion  factors  for  numeric  ficifis:  (4)  legends  for  abbreviated  data; 
(5)  accuracy;  ((?)  trailer,  e.g.  summar\^  totals,  end-oboutput  labels,  etc, 

4.2.3.2  Sample  Outputs 

Provide  illnstrative  examples  of  each  type  of  operational  oulput.  In  each 
case,  discuss  (l)  the  meaning  and  use  of  control  data  applied;  {2)  the  source 
and  characteristics  of  the  data  processed:  (3)  pertinent  facts  about  the 
calculations  made  by  tlic  software:  (4)  characteristics,  such  as  the  presence 
or  absense  of  items  under  certain  other  conditions  of  the  output  generation, 
other  ranges  of  input  values,  or  different  units  of  measure. 
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4.3  Performance  Characteristics 

Desoril>e  the  performance  characteristics  of  interest  to  the  operator, 
Incliicliag  where  appropriate:  (l)  quantity  of  input  and  output;  (2) 
throughput  rate;  (3)  cost  of  seivicc;  (4^  turn-around  time:  (5)  reliuldlity:  (6) 
quality  of  service. 

4.4  Security  and  Privacy 

Descrifjc  security  and  privacy  measures  implemented  in  the  program  that 
restrict  operations  or  guard  data  integrity  via  authorization  keys,  priorities, 
protocols,  etc.  Instruct  the  operator  what  features  are  operative  williin  the 
several  autfiorization  levels,  and  identify  penalties  for  inadvertent  or 
malicious  misuse.  Provide  warning  and  cautionary  information,  if 
applicahle. 

4.5  Operational  Constraints 

Descrtfie  specific  restrictions  that  are  placed  on  program  features  and 
options  hy  the  program  (internal)  design  or  hy  the  operational  or  system 
enviromnent  (external).  Give  a lirief  statement  of  supporting  rationale  for 
such  constraints  and  limitations,  if  deemed  to  he  of  value  in  operator 
understanding.  Defer  descriptions  of  procedural  constraints  to  Section  5.5. 

5.  OPERATIONAL  PROCEDURES 

'I'his  section  of  the  document  should  provide  a concise  and  complete 
specification  of  the  operational  procedures  to  lie  followed  by  an  operator 
for  initializing,  running,  and  terminating  program  operations  in  a correct 
and  efficient  manner.  Additionally,  material  should  lie  provided  that  will 
allow  an  operator  to  recognize  alarms  or  improper  operating  conditions 
and  to  initiate  recover)^  or  reinitialization  procedures  with  a minimum 
impact  oil  overall  program  operations. 

The  material  outlined  here  may  be  integrated  as  appropriate,  rather  tlian 
scgmentcfl  as  delineated  in  the  hienirchy  below. 

5.1  Setup  and  Inittation 

5.1.1  IVotocols 

Describe  the  operations  protocols  neees’sary  to  initiate  a nin,  sulmiit 
Input,  and  receive  output . Discuss,  as  appropriate:  (l)  opening  a computer 
work  order:  (2)  assignment  and  use  of  [passwords  and  account  codes:  (3) 
authorization  to  use  system  and/or  data  base  files;  (4)  assignment  of 
permanent  private  files;  (5)  Instructions  for  pickup  or  delivcr\^  of  I/O 
interactive  arifl  batch  protocols,  etc. 
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5.1.2  Setup  Procedures 

Describe  the  setup  procedures  as  a series  of  sequential  steps  or  cliccldist 
that  must  he  performed  in  preparing  for  operation.  Identify  all  cquipincrH 
(computer,  standard  peripheral.^,  sjiecial  or  unique  hardware.  ctc\)  and 
softAvare  required  for  siiccessfid  operation. 

5.1. 2.1  Hardware  Setup 

Provide  complete  instructions  and  procedures  for  connection  (or 
disconnection)  of  hardware  elcTiicnts  rcqtiired  for  each  given  application. 
Describe  the  hardware  configuration  for  each  in  terms  of  modes, 
operational  controls,  and  data  flow  paths.  Include  annotated  diagrammatic 
representations  where  appropriate.  DifFerentiate  between  input  and  output 
devices.  Specify  any  special  calibration  procedures  necessaiy'  to  verify  the 
operational  condition  of  individual  equipment  or  of  tlie  total  system, 

5 i .2.2  Software  Setup 

Provide  complete  iustnictions  for  program  setup,  loading,  and  initiation 
of  execution.  Identify  the  software  to  be  loaded  and  the  medium  on  which 
it  resides.  Identify  tlie  peripheral  from  which  the  program  is  to  be  loaded. 
De.scribe  in  detail  any  manual  fill  procedures  to  be  followed  in  loading  the 
software  into  inemor\^  List  any  loader  prompting  messages  that  might  be 
directed  to  the  operator.  Indicate  the  operator  inputs  required  to  respond 
to  prompting  or  to  control  the  loading  process.  Identify  loader  responses  to 
operator  input.  Provide  e.vamples  of  the  form  and  content  of  operator 
inputs  and  system  respon.sos.  Refer  to  appropriate  appendices  wherever 
applicable. 

If  different  operating  environment  (sy.sten\,  equipment,  or  program) 
configurations  are  needed  for  different  tvjses  of  nins  (such  as  pre-run. 
checkout  or  calibration  runs),  then  give  setup  and  initialization  procedr.res 
for  each.  Identify  critical  operations,  alarms,  and  error  messages. 

5.1.3  liiitialr/;itioii 

As  in  the  setiip  procedure,  describe  the  initialization  process  in  terms  of 
a series  of  sequential  steps  that  must  be  performed  to  properly  initialize  the 
software  for  execution.  Initialization  should  introduce  the  software  to  the 
environment,  identifying  the  control  source,  the  hardwarc/softwarc 
configuration.  I/O  constraints,  etc.  If  system  peripherals  such  as  disks  or 
magnetic  tapes  must  lie  initialized,  indicate  the  procedures  necc;^sar>^  to 
prepare  them  for  program  operation. 

5.1. 3. 1 Paranict  ers 

Identify  standard,  nominal,  or  default  values  of  parameters  already 
incorporated  ijito  the  program.  Specify  parameter  values  that  the  operator 
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is  required  to  initialize  and  give  instnietions  for  doing  so.  If  initialization 
can  l>e  performed  from  a remote  sotirce,  reference  the  remote  operations 
manual  Identify  ativ  constraints  placed  on  parameter  values  with  regard  to 
any  specific  mode  of  operation,  such  as  inaimal  or  automatic  operation. 

5. 1.3.2  Calibration 

Initialization  may  also  require  the  ealihrating  of  special  cquipineut  that 
cau  only  be  performed  in  conjunction  with  the  operating  software.  Specify 
the  procedures  to  lv'  followed  during  such  a calibration, 

5. 1.3.3  Operational  Inteniciion  During  hutiali/idion 

V.ist  prompting  messages  that  may  be  directed  to  the  o|>erator.  Indicate 
the  operator  inputs  required  to  respond  to  prompting  or  to  control  the 
initialization  process.  Identify  the  periplicrals  to  whicli  system  output  is 
directed  and  list  the  responses  to  operator  inputs  and  program  responses. 


5.2  Input  Handling 

Describe  the  procedures  for  gathering  input  data  and  putting  it  in  the 
format  retniired  for  operatiiig  the  program.  Such  procedures  might  include: 
(l)  the  method  of  extracting  data  from  source  documents  or  fdcs;  (2)  usage 
of  data  preparation  aiwl  editing  aids  or  other  software;  (3)  usage  of  special 
services,  such  as  kcypimch  operators;  (4)  a checklist  to  determine  rapidly  if 
cverv'thing  has  been  done;  \5)  special  considerations  for  altcrinitivc  input 
media;  (6)  special  considoratious  for  hatch  vs.  interactive  operation;  (7) 
qiiality  control  c.g..  irtstmetions  for  checking  reasonableness  of  data, 
actions  to  be  taken  when  data  ap]>ears  to  he  received  in  error, 
documentation  of  errors,  etc.;  (8)  disposition,  e.g,,  instructions  for  retention, 
return,  release,  or  distribution  of  input  data  received;  etc. 


S-3  Operational  Control  Procedures 

5.3.1  Operational  Control 

Operational  control  denotes  program  control  after  setup,  initiation,  and 
initialization  have  been  completed  and  program  execution  has  begun. 
During  execution,  especially  in  real-time  operations,  operator  interaction 
with  the  system  may  no  longer  he  confined  to  a series  of  sequential  inputs, 
hut.  irstead,  may  V^e  described  as  a reaction  to  system  behavior. 

If  processing  requires  or  permits  interaction  or  monitoring  by  the 
operator,  provide  instructions  for  terminal  operations.  Describe  (l)  data  or 
parameter  input  devices  and  procedures;  (2)  control  dt>viecs  and 
instructions;  (3)  cassette/tape  device  operation;  (d)  nm  interruption/ 
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recover)’;  (o)  special  terminal  dcvicc-S  c.g..  plotters;  etc.  Provide  sainples  to 
illustrate  each. 

54^2  Termination 

Describe  procedures  for  terminating  operations  as  an  orderly,  sequeuMal 
series  of  steps.  Differentiate  between  normal  termination  and  abnormal  or 
emergency  termination,  attd  describe  the  conditions  associated  with  each 
type.  Describe  liriefly  the  effect  of  termination  on  I/O  devices  so  that 
peripherals  arc  not  deallocated  prematurely.  If  a sinntnar)'  of  prograin 
activity  is  available,  specify  the  procedure  for  generating  such  an  activity 
report.  If  system  prompting  is  provided,  list  the  messages  and  identify  the 
operator  inputs  required  to  respond  to  cadi.  Refer  to  appropriate 
appendices  if  applicable.  Cive  examples  as  appropriate. 

5.4  Output  Handling 

Describe  policies  and  procedures  within  the  operational  environment  for 
handling  the  output  data.  Typical  instructions  cover  (l)  handling-  disposing, 
dis.seminating,  and  routing  of  the  various  forms  of  output:  (2)  storing  or 
archiving  of  output  items  for  their  later  retrieval;  (3)  status  reporting  based 
on  output  parameters;  (4)  extracting  and  summarizing  of  information:  and 
(d)  checking,  auditing,  or  inspecting  the  output  tlata, 

5.5  Operational  Restrictions  and  Limitations 

Identify  and  explain  e.xceptions  and  restrictions  in  the  procedures  for 
receiving  or  preparing  or  entering  input,  operating  the  prograi?.i,  or 
b*anclling  the  output.  Such  material  might  address  i\)  limited  availalnlity  of 
input  devices;  (2)  security  considerations;  (3)  processing  cost  vs.  tiinc-of-day 
limitation.s;  (4)  restrictions  on  amoimt  of  input  or  output;  etc.  The 
restrictions  and  exceptions  discussed  here  arc  restrictions  in  operational 
procedures,  rather  than  in  the  program  applications. 

5.6  Interrupt,  Recovery,  and  Restart  Procedures 

If  not  adequately  covered  in  other  parts  of  the  nuimiah  describe  (l) 
detection  criteria  and  procedures  for  anomalous  program  behavior;  (2) 
meanings  of  error  messages,  codes,  or  indicators;  (3)  prescribed  emergency 
actions  by  the  operator;  (4)  procedures  for  correcting  input  errors;  (o) 
procedures  for  restart/ recover)^;  etc. 

Describe  the  type  and  form  of  status  and  performance  parameters 
displayed  by  the  program.  Identify  the  peripherals  to  which  .such 
information  is  directed.  Include  tables  or  charts  that  list  and  define  status 
and  performance  output.  Include  e.xamples  of  actual  display  output,  if 
available. 
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Provide  a convenient  method,  such  as  a decision  table,  for  identifying 
sijigle  and  multiple  points  of  failure,  and  state  what  operator  action  should 
he  performed  witli  each  type  oi  failure.  List  the  steps  to  l)c  taken  by  tlie 
operator  for  each  moHiod  of  recover)^  and  reiiiitialization.  Provide  a list  of 
operator  inputs  and  expected  system  responses.  Include  examples  of  eacli 
typo  of  recoverx'  ujkI  reinitialization  procedure.  Refer  to  appropn'atc 
U]  pendices  where  applicable. 

6.  OPERATIONS  SUPPORT 

This  section  of  the  operator  manual  contains  instructions  for  providing 
the  support  functions  nccessaiy^  to  the  day-to-day  operation  of  the  software, 
not  covered  by  standard  procedures  or  by  enviromncntal  consideratiojis 
pre V i ous ly  closer i bed. 

6.1  Operational  Utilities 

Describe  operational  utilities  used  for  supporting  program  operatioiis, 
and  give  procedures  for  using  them  (or  references  to  such  manuals,  if 
general-purpo.se  and  readily  available),  as  applicable.  Such  utilities  might 
inciude:  (l.)  file  management  and  maintenance  facilities;  (2)  data  conversion 
software;  (3)  program  test  l)enchmarks,  test  aids,  test  generators,  etc.;  (4) 
hurdware-caliiiration  programs:  (5)  diagnostic  or  deluig  aids;  (O)  perform- 
ance and  utilization  monitors;  (7)  data  editors*;  etc. 

6.2  Management  Information  Reporting 

Describe  requirements  and  procedures  for  management  iiiformation 
reporting  incurred  by  program  operations,  lopics  in  this  section  might 
include  such  things*  as  (l)  requirements  for  reporting,  e.g,,  frequency, 
conditions,  report  type,  etc.;  (2)  accounting  procedures:  (3)  operations 
schedules;  (d)  resource  juauagement;  (5)  utilization  statistics;  (6)  anomaly 
status;  etc. 

6.3  Logistics 

Insofar  a.s  it  is  the  responsibility  of  the  readers  of  the  manual  to  supply 
expendable  materials  for  the  operation  of  the  program,  provide  procedures 
or  referejice.s  that  describe  how  siich  materials  are  to  lie  olitained,  stocked, 
dLstributed,  etc.,  unless  these  arc  items  covered  by  operational  standards 
cited  earlier, 

6.4  Anomaly  Reporting 

Describe  requirements  and  procedures  for  submitting  operational 
problem /fail  lire  reports  to  the  proper  program  maintenance  personnel,  or 
for  notifying  management,  users,  or  otliers*  of  anomalies  detected  and 
repaired  (as  an  operational  service). 
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7.  APPENDICES 

Appended  material  ma)'  include,  hut  are  not  limited  to,  explanalor)^ 
material  atKl  references  of  an  auxiliar\^  nature,  inserted  directly  or  hound 
separately  for  convenience.  The  following  suggested  topics  are  typical 
Appendices  may  designated  as  '^Appendix  A/'  etc,,  if  desired,  rather  than 
by  the  Dewey-decimal  system  given  here. 

7.1  Glossary 

Give  a list  of  innemonics,  acronyms,  and  unfamiliar  or  specially  used 
terms  appearing  in  the  manual;  provide  definitions  for  each. 

7.2  References 

Provide  a bibliography  of  references  to  other  documents  appearing  in 
this  manual  Give  a brief  indication  or  abstract  of  what  is  being  referred  to 
in  each  work, 

7.3  Input  and  Output  Formats 

Provide  detailed  formats  and  syntax  for  operator  inputs  and  outputs, 
together  with  associated  response{s)  as  supplementary  material  to  Section 
4.2,  Define,  as  appropriate:  (l)  data  base  I/O  formats,  parameters,  and 
control  characteristics;  (2)  communications  device  I/O  formats,  parameters, 
and  control  characteristics;  etc. 

7.4  Auxiliary  Tables 

Assemble  in  tabular  form  auxiliar>^  reference  material  needed  for 
program  operations  that  is  better  located  in  an  appendix  rather  than  in  the 
text  proper.  Display  each  table  in  a separate  subsection  (7.4.0  and 
introduce  or  explain  the  use  of  each  table  narratively. 

7.5  Summary  of  Operations 

Provide  an  abbreviated  description  of  each  of  the  operational  features  for 
the  knowledgeable  operator.  This  summary  should  be  devoid  of  tutorial 
explanations,  containing,  instead,  only  technical  descriptions  or  definitive 
examples  for  quick  reference.  Such  material  may  be  annotaterl  to  index  the 
summary  forms  to  pertinent  sections  of  the  manual  containing  detailed 
information. 

7.6  Detailed  Examples 

Display  the  operation  of  the  program  via  sample  runs  from  beginning  to 
end.  Show  all  input,  indicate  all  interactions  in  a timely  sequence,  and 
display  all  operator-pertinent  output.  Give  examples  of  normal  and 
abnormal  nins,  and  illustrate  the  procedures  followed  in  each  case. 
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This  appendix  contains  an  outline  of  topics  typically  considered  for 
inclusion  in  the  Software  Test  Report  (STR).  The  items  listed  are  not 
exhaiLstive  nor  arc  all  those  given  necessarily  applicable  to  a particular 
development.  Rather,  the  topics  contained  herein  should  be  considered  as 
candidates  for  coverage  in  software  test  plans  and  test  reporting. 

The  STR  is  a summary  of  test  plans  and  test  results;  but  it  may,  in  some 
cases,  also  include  the  test  archives  (by  attachment  or  separate  volumes),  if 
these  are  deemed  to  be  of  value  for  historical  purposes  or  for  reference  in 
later  maintenance  activities.  Tasofar  as  test  requirements  are  contained  in 
the  SRD,  test  plans  are  included  in  the  SDD,  and  test  specifications  arc  part 
of  the  SSD,  the  STR  need  not  repeat  such  material  but  merely  reference  it 
(when  in  compliance). 

The  STR  contains  the  reviewablc  proof  that  delivery  and  acceptance 
criteria  have  been  met,  that  the  development  phase  can  properly  terminate, 
and  that  the  program  and  its  documentation  are  ready  for  a formal  transfer 
into  maintenance  and  operations  activities.  The  outline  below,  therefore, 
covers  the  major  items  needed  for  ter;hnical  and  management  review.  The 
SRD  may  identify  exactly  what  items  of  an  optional  nature  should  appear  in 
the  STR.  However,  at  a minimum,  the  STR  should  be  sufiRcient  for 
verifying  the  quality,  accuracy,  and  completeness  of  the  software 
deliverables  in  meeting  SRD  requirements, 

Figure  J-1  is  a top-level  graphical  outline  of  the  document  organization; 
greater  detail  is  provided  in  the  detailed  outline  that  follows^ 
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SOFTWARE  TEST  REPORT 
Detailed  Table  of  Contents 


FRONT  MATTER 


Title  Page.  Provide  a title  page  containing  (l)  document  number;  (2) 
SOin'WARE  TES'r  REPORT;  (3)  program,  subsystem,  and  system  titles;  (4) 
publication  date;  (,5)  signature  lilock  with  name  of  preparer  and  others,  as 
required  Signatures  arc  to  l>e  supplied  at  STR  completion.  Date  reflects 
time  of  last  change  to  any  item  in  the  STR. 

Abstract.  Cdve  a brief  abstract  that  suininarizes  the  program  test  and 
acceptance-readiness  status. 

Change  Control  InfoniwHon.  Provide  a statement  that  relates  the  level  of 
change  control  and  authority  exercised  on  this  document*  and  procedures 
for  update. 

Distribution  List.  Provide  a distribution  list  of  all  parties  with  necd-to- 
kn<nv  statiLS  of  the  software  acceptance  readiness  who  are  to  receive  copies. 

Distribution  liiforination.  Provide  a statement  that  tells  how  additional 
copies  may  he  obtained. 

Table  of  Contents,  Provide  the  detailed  table  of  contents  for  the  STR, 
which  lists  section  number,  title,  and  page  of  cvety  item  with  a heading. 


TEXT  OF  REPORT 


1.  INTRODUCTION 

1.1  Purpose 

Provide  a brief  statement  of  the  purpose  of  this  document. 

1.2  Scope 

Define  the  configiiration(s)  tested  and  the  extent  to  which  this  docuineiit 
reports  on  test  plans,  test  results,  QA  audit  findings,  exception  identifica- 
tion, etc. 
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1.3  Applicable  Documents 

List  all  c’oiit rolling  documents,  applicable  standards,  etc,,  governing  the 
production  of  the  results  reported  lierein, 

1.4  Test  Overview,  Goals,  and  Criteria 

Brielly  describe  tlie  objectives,  general  pliilosophy,  approach,  and  overall 
strateg)'  of  lest  activities.  Highlight  the  program  functions,  test  plans  and 
goals,  operational  interfaces,  testing  environment,  acceptance  criteria,  and 
QA  invotveinciit.  Correlate  this  material  with  requirements  stated  in  Hie 
SHID,  Identify  diflerenccs  between  test  and  operations  interfaces  and 
environments  that  couUl  affect  program  operation  or  assessment  of  its 
acceptability. 

1.5  Test  Result  Summary 

Discuss  the  various  test  runs,  the  extent  of  these  tests,  and  the  results  of 
the  testing  activity.  Identify  major  discrepant  items  or  problems,  and  give  a 
brief  suinmaiy  of  the  QA  audit.  As\sess  the  effei?ts  that  difforent^es  fietween 
the  test  envirojimeul  and  the  actual  operational  envimnmetit  may  have  had 
on  the  demonstration  of  capabilities.  State  the  degree  to  w^hich  the  results 
comply  with  SbD  requirements.  Summarize  resource  utilization  and 
schedule  performance,  as  appropriate  to  the  ro\n'ewing  authority. 

2,  TEST  PLANS  AND  CONFIGURATIONS 

2.1  Schedule  and  Resources 

Show  tlie  at’ceptance  test  schedule  with  events,  milestones,  te.sourcc 
(manpower,  computer,  etc.)  utilization,  and  time- phased  loading  of 
resources  as  actually  incurred. 

2.2  System  Configuration 

Identity  the  system  configiiratitms  used  in  testing  and  QA.  State 
differences  lictweeji  test  and  operational  configurations,  and  a.s.sess  the 
itnpact  of  these  difl'erences  on  software  acceptability. 

2.3  Operational  Configuration 

Identify  the  operational  configurations  ii.sed  during  testing  and  QA.  State 
difference.s  lielween  test  and  operational  configurations,  and  asso.ss  tlic 
impact  of  these  differences  on  software  accept ul)i I ity. 

2.4  Facilities,  Materials,  Support,  and  Training 

Identify  the  locations  and  date.s  of  tests,  participating  organiza lions, 
special  test  equipment  or  software,  personnel  skills  (user,  operator, 
developer,  clerical),  and  materials  required  for  test  activities  (c.g., 
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documentation,  loadable  program,  test  data,  sample  output,  expendable 
supplies,  etc*).  Discuss  training  of  test  personnel  type  and  level,  the  use  of 
multi-shift  operation,  etc,,  its  appropriate  to  report  pertinent  support-level 
activities, 

23  Test  Criteria  and  Evaluation 

Describe  the  rules  used  to  evaluate  test  results,  prioritize  anomalies, 
register  QA  faults,  etc.  Reference  or  restate  such  criteria  given  in  the  SRD, 
Cite  existing  standard  testing  criteria  and  SSD  test  specifications,  as 
appropriate.  Identify  standard  tests  and  benchmarks.  State  and  describe 
exceptions  to  test  standards  and  standard  tests.  Describe  how  these  criteria 
fulfill  SRD  requirements,  if  neccssar>\ 

Describe  the  techniques  used  for  manipulating  the  test  data  (manual, 
automatic)  into  a form  suitable  for  evaluation,  or  for  comparison  of  aefual 
results  with  predicted  results. 

3.  INTERFACE  TESTS 

-'s 

3.1  System  Interface  Tests 

Describe  the  system  interfaces  tested  (including  I/O),  the  software 
functions  that  exercise  these  interfaces,  the  tests  that  verify  these  interfaces, 
and  the  progression  of  tests,  one  to  the  next,  if  pertinent.  In  top-down 
development,  these  interfaces  are  normally  checked  early,  but  informally, 
during  developmental  (correctness)  testing.  Citation  of  the  results  of 
developmental  tests  may  be  sufficient  here,  in  some  cases. 

3.2  Operational  Interface  Tests 

Describe  the  operational  interfaces  tested,  the  software  and  human 
functions  that  exercise  these  interfaces,  the  procedures  and  test  data  that 
verify  these  interfaces,  and  the  manner  in  which  progression  was  made  from 
one  test  to  another,  if  pertinent.  Although  these  tests  may  have  been 
simulated  during  development  testing,  it  is  unlikely  that  the  actual 
operational  environment  was  verified.  These  tests,  therefore,  will  probably 
require  separate  demonstration  during  the  acceptance  test  phase. 

3.3  Program  Interface  Tests 

Describe  the  program  interfaces  with  libraries,  data  buses,  and  other 
programs,  the  tests  tliat  verify  these  interfaces,  the  results  of  such  tests,  etc. 
In  top-down  development,  these  interfaces  are  normally  checked  early  in 
development  testing;  separate  demonstration  for  acceptance  may  not  be 
necessary  in  such  cases. 
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4.  FUNCTIONAL  TESTS 

4.1  Operator  Control  Tests 

Dest’rihc  iK‘i.‘optaiu:e  tests  esctutecl  to  verify  operator  controis  and 
responses,  and  (he  extent  and  results  of  these  tests.  Assess  the  fiei^ree  of 
eompliauee  wit  h software  rei|iiireiuents  doeiimont  and  operations  manual. 

4.2  Operational  Verification  Tests 

l>escribe  act  epluiUH?  tests  executed  to  verily  end-to-ond  iuuctiomd 
eapahilitios,  diai^nostic  features,  and  error  responses  of  the  program,  and 
the  extent  atui  results  of  these  tests. 


4.3  Performance  Measurement  Tests 

Identify  the  performance  parameters  ealihraied  or  measured  by  tests,  and 
compare  the  results  with  the  reqtn'red  or  stieclfied  \^diies  (SUD  nr  SSDl 
Assess  the  degrct?  to  which  performance  meets  program  requirements  and 
specificattons. 

4.4  Security/ Privacy  Tests 

U tluM'e  are  requirements  (SUD^  t>r  specifications  (SSH^  to  demonstrate 
security/privaev  features  of  the  program,  then  describe  the  tests  atid  test 
results.  Assess  the  degree  of  compliance  with  requirements  and  specifica- 
tions implied  bv  this  demonstratiorc 

4.5  Interrupt.  Recovery,  and  Restart  Tests 

Descrilie  tests  and  test  results  that  demonstrate  capalulities  for  program 
interruption  and  reeoverx'  or  restart,  us  required  (SRD)  or  specified  \SSD\ 
Assess  the  degree  of  compliani  e with  requirements  and  specificatfons. 


5.  DEVELOPMENT  TESTS 

5.1  Normal  Data  and  Conditions  Tests 

Summari7.e  tiie  results,  extent,  and  sc^)pe  of  development  (production) 
tests  performed  t;u  verify  the  processing  algorithms,  data  structuring,  and 
I/O  under  normal  it\put  data  and  normal  operating  conditions, 

5.2  Limit  and  Overload  Tests 

Summarise  the  results,  extent,  an<l  scope  of  development  IproducHon) 
tests  performed  to  verify  or  calibrate  the  program  response  to  limiting-ease 
and  oiit-of-iauge  input  data,  real-time  operational  overloads,  and  liovond- 
normal  conditions  that  reflect  on  the  input  dynamic  range  of  the  program. 
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S.3  Erroneous  Data  and  Palhotogical  Conditions  Tests 

Smninari?.c  the  rosultK,  extent,  and  seopc  of  development  (production) 
tests  performcci  to  verify  or  eaUlirate  Mic  ability  of  the  program  to  detect 
and  reirover  from  erroneous  input,  real-time  operational  failures,  and 
abnormal  operating  conditions, 

6.  DELIVERY  READINESS 

6.1  Deliverables 

Give  an  inventor>^  list  of  dcliverai>le  software  itettis  that  identifies  for 
each:  (0  item:  (2)  identification  number;  and  (.3)  release  date, 

6.2  Exceptions  and  Liens 

Descril)c  deflcieiKnes  of  the  software  as  dcmotistrated  by  tests, 
inspections,  Q\  audit,  or  other  means,  and  prioritize  these  into  categories, 
such  as:  (a)  critical  to  successful  program  operation  as  required:  (B) 
degradevs  performance  or  iiKTcases  operational  risk:  (C)  <loos  not  prevent 
s(d*tware  from  operating  and  satisfying  requirements,  but  is  operationally 
undesirable;  work-around  neccssarv'.  In  addition,  lEidicate  those  discrepant 
items  that  can  l^c  negtjtialed  for  aceeptai>ility.  those  that  can  lu'  acceptwi 
under  lien  for  removal  by  a specified  date  after  dehverx,  and  those  that 
cannot  be  accepted  in  software  transferred  to  operational  status. 

6.3  Quality  Assurance  Audit  Report 

Summarize  the  QA  activities  in  certifying  tlio  program  for  acceptance. 
Report  the  results  of  audits  arid  reaudits  of  the  SSD  dneu mentation  against 
the  cckIc,  as  well  as  other  materials  audited.  Identify  deficient  or  marginal 
itents  (code,  tests^  and  documentation). 

6.4  Confidence  Measurernent 

Discuss  the  method  used  to  calibrate  the  accept auce  tests  and  the  level 
of  confidence  plannerl  in  calibration  testing.  Summarize  the  results  of  such 
tests,  aud  state  tlie  i;ompuled  level  of  confidence  in  the  program  and  in  the 
ability  of  acceptance  tests  to  uncover  anomalies,  if  present  (c,g,,  see 
Chapter  9). 

7.  APPENDICES 

Appendices  may  include,  but  are  not  limited  to,  auxiliar\^  material 
inserted  (lirectly  or  bound  separately  for  convenience.  The  following  topics 
arc  typical  Appendices  may  be  designated  as  ^'Appendix  A/*  etc,,  if  desired, 
rather  than  by  the  Dcwey-decimal  system  given  here. 
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7.1  Glossary 

List  the  mnemonics*  acronyms*  and  specially  used  terms  appearing  in  this 
document,  and  give  a short  definition  of  each, 

7.2  References 

Provide  a list  of  source  documents,  standards,  procedures*  manuals,  etc., 
referenced  in  this  document,  indicate  the  subject  matter  and  purpose  of 
each  such  item  in  the  list, 

7.3  Anonndiy  Summary 

Provide  a summur>’  list  of  all  discrepancies  in  the  software  package.  For 
each*  give  the  anomaly  number*  the  program  version,  the  reported  date,  a 
brief  description*  the  priori t>'  categoiy^  (c.g.,  see  6.2,  above),  the  urgency  for 
correction*  parties  responsible  for  correction*  present  statas,  the  means  of 
disposition,  and  other  pertinent  information.  Provide,  then,  as  appropriate, 
a detailed  breakdown  or  backup  description  and  history  of  each  of  the 
individual  discrepancies  (prol)ably  a compendium  of  anomaly  report  forms* 
status  forms,  statistics  forms,  etc.). 

7.4  Detailed  Test  Summary 

When  appropriate  to  include  summary  results  of  individual  tests  or  more 
detailed  descriptions  of  the  tests  performed,  do  so  in  this  appendix.  Discuss 
the  general  method  or  strateg}^  of  the  testing,  and  describe;  (l)  the  type, 
volume*  frequency  of  input  used;  (2)  the  extent  of  testing  performed  (total 
or  partial)  with  rationale  for  choice;  (3)  method  of  recording  results  and 
other  information  about  the  tests;  (4)  limitations  on  tests  due  to  conditions, 
such  as  interfaces,  equipment,  personnel,  and  data  bases;  (5)  controls,  such 
as  manual,  semi-automatic,  or  automatic  insertion  of  inputs*  etc.;  (6) 
sequence  of  operations  or  progression  from  one  test  to  another  so  that  the 
entire  test  cycle  was  complete;  etc. 

7.5  Test  Archive 

This  appendix,  if  present,  may  contain  the  entire  collection  of  test 
outputs  over  the  entire  project  lifetime  (probably  as  separate  volumes),  or 
may  contain  only  material  selected  as  supportive  to  this  document  or  as 
necessaiy  for  future  historical  or  reference  purposes. 
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The  purpose  of  the  Softwiirc  Maintonaoce  Manual  is  to  provktc  the 
sustaining  and  mainteiumce  personnel  with  information  nccessar>"  to 
understand  a program  in  its  operating  onvironincnl,  and  to  list  the 
procedures  for  correcting  errors,  updating  documentation^  making  progrant 
modifications,  etc.  This  moitograph  has  always  assumed  tlial  the  SSD  and 
user/operator  mautuds  form  the  primarj  sustaining  and  maintenance  source 
documents. 

The  maintenance  manual,  therefore,  does  not  repeat  this  information. 
Instead,  it  gives  procedural  instructiotLS  for  performing  the  sastaining  and 
maintenance  activities.  As  with  others  manuals  described  in  tliese 
appendices,  maintenance  prot:cdurcs  should  be  acciunuUited  and  written 
concurrently  with  the  other  program  production  activities.  Even  when  the 
maintenance  and  operations  organization  has  different  configurations  aiul 
standards  than  implementors  (and  will,  therefore,  write  this  manual 
themselves),  the  skeleton  of  procedures  used  during  development  cun  be  of 
tremendous  benefit  as  the  basis  of  the  manual  to  Ihd  written.  Figure  K-1  is  a 
top-level  view  of  the  suggested  organization  for  a Maintenance  Manual. 
The  remainder  of  this  appendix  is  a detailed  outline  with  guidelines  for 
writing  the  material  suggested  As  with  the  user  and  operator  manuals, 
topics  described  in  this  appendix  are  presented  in  checklist  hierarchy; 
actual  writing  of  the  manual  may  well  integrate  maintenance  functions 
with  interfaces  and  procedures,  so  as  to  form  a set  of  monolithic 
descriptions  of  the  subjects  covcrerl. 


407 


Rgure  K-1,  Top>!evel  view  Of  the  SMM  table  of  contents 
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SOFTWARE  MAINTENANCE  MANUAL 
Detailed  Table  of  Contents 


FRONT  MATTER 


Title  Page.  Provide  a title  page  containing:  (l)  document  munber;  (2) 
SOFTWARE  MAINTENANCE  MANUAI.;  (3)  program,  subsystem,  and 
system  titles;  (4)  publication  date:  (5)  author  and  authorization  signatures, 
as*  appropriate;  and  (6)  releasing  organizatioa 

Abstract,  Give  a brief  abstract  that  summarizes  the  purpose  and  usage  of 
the  manual. 

Chuitge  Control  Information,  Provide  a statement  that  specifies  the  level 
of  change-control  authority  for  the  manual,  and  state  procedures  for 
submitting  change  requests  and  reporting  of  errors, 

Distrihutioii  Infonnation,  Provide  information  that  sells  how  copies  of  this 
document  may  he  ol>tained. 

Table  of  Contents.  Provide  a detailed  table  of  contents  for  the  manual, 
listing  section  mimher,  title,  and  page  of  every  item  with  a heading. 


TEXT  OF  MANUAL 


1.  INTRODUCTION 
1.1  General  Description 

Provide  a brief  statement  that  identifies  the  program,  system,  and 
environment  covered  by  this  manual.  Give  the  program  title,  tag  or  label, 
and  programming  lahguago(s).  Perhaps  also  appropriate  in  this  description 
are  relationships  to  other  maintenance  activities,  alternate  environments, 
orgum‘zatioj\al  responsilu'Hties,  and  maintenance  programmer  rcs|50tisibili- 
tics. 


1.2  Orientation  and  Scope 

Identify  the  intendc<l  users  of  this  manual  their  assumed  backgrounds, 
the  level  of  skill  required,  and  the  extent  to  w'hich  this  manual  is  self- 
contained.  Describe  the  scope  of  this  manual  as  it  pertains  to  the 
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completeness  with  which  it  covers  maintenance  matters.  Identify  any 
significant  limitations  in  the  program  maintenance  as  levied  by  this  manual, 

13  Applicable  Documents 

Identify  all  documents,  controlling  or  inforinationuh  which  apply  to  or 
regulate  the  maintenance  activities  associated  with  the  program. 

1.4  Maintenance  Overview 

Provide  a brief  overview  of  the  maintenance  functions  and  the  general 
policies  and  procedures  that  apply  to  each.  Identify  salient  characteristics 
of  the  maintenance  activities,  such  as:  (l)  change  control;  (2)  resource 
estimation;  (s)  reporting;  (4)  operations/uscr  liaison;  (5)  developer  liaison; 
(6)  division  of  labor;  (7)  support  requirements;  etc, 

1.5  Guide  to  the  Use  of  the  Manual 

Explain  how  this  guide  is  to  be  used  by  maintenance  personnel 

2.  STANDARDS  AND  CONVENTIONS 

This  section  describes  standards  impo.sed  on  the  maintenance  organiza- 
tion (or  used  by  them)  and  conventions  (e,g.,  notations  and  terminology) 
applied  in  this  manual 

2.1  Maintenance  Organization  Standards 

Identify  or  reference  applicable  existing  organizational  maintenance 
standards,  state  any  exceptions  to  these  standards  necessitated  by  this 
program,  and  describe  the  alternate  practices  to  be  used, 

2.2  Maintenance  Programming  Standards 

Identify  or  reference  applicable  existing  programming  documentation 
and  testing  standards  to  he  applied  in  program  maintenance,  state  any 
exceptions  to  these  standards  nece,ssitated  by  this  program,  and  describe  the 
alternate  practices  to  be  used.  State  the  language{s)  to  be  used  for  program 
modifications. 

2.3  Maintenance  Conventions 

Define  natations,  terms,  and  other  conventions  or  assumptions  used 
generally  throughout  the  manual.  Include  such  item,s  as  ways  of 
distinguishing  literal  fields  from  syntactic  variables  in  descriptions  of  input 
and  output  formats,  means  for  differentiating  inputs  and  outputs  in 
interactive  examples  of  procedures,  non-standard  mathematical  usage, 
special  acronyms,  etc.  Describe  maintenance  conventions,  such  as  file 
naming  of  scratch,  update,  and  test  files. 
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3.  MAINTENANCE  ENVIRONMENT  AND  INTERFACES 

3.1  Organizational  Interfaces  and  Support 

Describe  the  maintenance  organizational  enviromneiit,  responsibilities  as 
appropriate  to  perform  maintenance,  liaison  activities  with  others,  support 
required  for  or  available  to  maintenance  activities,  and  other  matters  of  an 
organizational  nature,  as  bencBcial  to  the  readers  of  this  maniiaL 

3.2  Hardware  Interfaces 

Identify  (by  reference  to  system  documentation  if  possible)  the 
equipment  required  for  operation  and  maintenance  of  the  program. 
Describe  any  unusual  features  used.  Include  such  information  as  (l)  size  of 
processor  and  internal  storage;  (2)  online  and  offline  storage  njedia  and 
devices;  (3)  online  and  offline  I/O  devices;  (4)  data  transmission  devices. 


3.3  Software  Tools  and  interfaces 

Identify  the  system  support  software  neerled  for  program  maintenance, 
and  describe  the  interfaces  in  enough  detail  so  as  to  prepare  the  reader  for 
the  functions  and  procedures  in  sections  to  come.  Include,  as  needed:  (l) 
operating  system;  (2)  coinpiler(s)  or  ussembler(s);  (3)  debug  facilities;  (4)  test 
data  generators;  (5)  text  editors;  (6)  data  management  s>'stems;  (7)  report 
generators;  etc*  Include  the  version  or  release  mimber  of  each  and  any 
unusual  features  u.sed. 


3.4  Data  Base  and  Library  Interfaces 

3,4*1  Data  Base  Interfaces 

Describe  or  reference  documentation  on  the  data  bases  required  or 
typically  used  for  maintenunce,  if  any.  Include,  as  appropriate,  information 
such  as  keys,  units  of  measurement,  format,  range  of  values,  names  of  files, 
location  of  the  data  element  dictionary,  etc. 

3,4.2  Library  Interfaces 

Identify  programs,  subprograms,  or  other  materials  in  libraries  that  are 
used  in  program  maintenance,  and  give  appropriate  references  to  detailed 
usage  information.  Give  a brief  description  of  the  usage  and  interfaces 
pertinent  to  this  manual. 


4.  MAINTENANCE  FUNCTIONS 

This  section  descril>es  functions  performed  in  maintaining  the  software, 
not  the  procedures  for  performing  these  functions. 
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4.1  Maintenance  Overview 

Describe  the  maintenance  tasks  in  siiimnarj^  fashion  as  an  introduction  to 
the  remainder  of  Section  4.  Ff  already  covered  in  Section  l,4»  so  state,  and 
omit  duplication,  rdentify  such  functions  as  (i)  anomaly  detection;  (2) 
anomaly  correction;  (3)  anomaly  report  custodianship  activities;  (4) 
software  modification  acth  ities;  (5)  cnginceriiig  change  control  activities; 
(d)  liaison  activities;  (7)  operations  support;  (8)  user  support;  (9)  special 
maintenance  functions. 

4.2  De$criptibn  of  Maintenance  Functions 

Detail  each  of  the  maintenance  functions  introduced  in  Section  4.1, 
above,  as  separate  subsections  (4.2./).  Use  a level  of  detail  sufficient  to 
describe  the  functioris  to  the  degree  required  to  apply  the  procedures  in 
Section  5. 

4.3  Documentation  Maintenance 

Identify  the  program  documents  in  the  custody  of  maintenance,  and 
describe  the  role  and  responsibility  of  maintenance  personnel  for  keeping 
these  documents  current.  Identify  resource  availability  or  limitations  for 
such  maintenance,  if  appropriate.  List  (or  reference)  criteria  and  approvals 
for  niuking  documentation  modifications,  quality  requirements  for 
redocumented  items,  requirements  for  QA  audit  or  recertification,  etc, 

4.4  Maintenance  Restrictions 

Identify  and  describe  or  reference  restrictions  placed  on  maintenance 
fimctioiis  and  activities  by  the  host  system  by  supporting  services,  by 
change  control  requirements,  by  the  maintenance  organization,  and  by 
availal>lc  resources. 

5.  maintenance  procedures 

This  section  describes,  in  robotic  sequence  detail,  the  steps  that  are  used 
to  perform  the  functions  described  In  Section  4. 

5.1  Program  Generation  and  Linkage*Edit  Procedures 

rdentify  and  describe  each  of  the  symbolic,  relocatable,  and  absolute 
dements  required  to  generate  the  program.  Detail  the  method  and  steps 
used  to  install  the  program  into  its  operational  environment  (ready  for 
operations  and  use).  Describe  job  control  code,  linkage-edit  (map)  code, 
etc.,  and  the  sequencing  required.  Cite  references  to  appropriate  manuals, 
detailing  the  various  program  generation  tools  used.  Give  specific  end-to- 
end  nmiiing  examples  of  each  case  (e,g.,  backup  tape,  symbolic  system  files, 
relocatable  system  files,  absolute  elements,  etc;.). 
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5.2  Program  Alteration  Procedures 

Dot  ail  t!u‘  motliod,  steps,  aiul  prolot^ids  used  to  anom  aliens  or 

make  <ul»er  rhan^os  in  t he  prom  aui  eotle.  Deserihe  I lie  use  of  lx?xt  edit  ors. 
assenihleKs^  or  4*tim|.)ilersu\  dohni;  and  other  fluickout  f:uMlitios\  binary  or 
symbolic  patch  eapalnlities,  oU\  Cive  reforeiu  os  to  mainials  deseribiiiiT  the 
details  of  the  software  tools  used.  Clive  speeitir  emd-to-end  running 
examples  oi  eat'h  alteration  method,  eomplele  with  all  of  the  job  eonirol 
i‘ode  iietnled  for  eveention. 

5.3  Anomaly  and  Status  Reporting  Procedures 

State  proeediires  for  handlite^  anomaly  repiirts.  such  as  loj^ivini;,  rei;nlar 
status  report  generation,  user/ ojiera tor  notification,  determination  of 
(>riorily  and  method  for  removal,  ett*. 

5.4  Special  Maintenance  Procedures 

Deserilie  any  special  maintenance  jiroccdures.  such  as  scbedulini;  of 
a^*(ivitu^s^  redocimu'iitatiou  proi'cdurcs,  [)roi;i:un  liackiip  t master^  handlinj>. 
Secainlv/intctinly  monitoriui;.  data  base  recovery,  and  hints  for  usini;  SSO 
and  other  manuals  in  mainUaiaiuv  aiMivities, 

5.5  Engineering  Change  Request/Order  Action 

Cove  protH'diircs  for  institutinj.;  or  evaluatini;  idian\»e  recjuesis.  for 
responding  to  (‘hange  orders  ii|)on  receipt,  and  for  notifying  upon 
compliance. 

6.  PROGRAM  VERIFICATION  PROCEDURES 

6.1  Testing  and  Reporting  Procedures 

Di'Si’rilie  the  procedures  f<ir  settling  up  tesls'  and  rc'certijication  of  tlie 
software,  either  gt'iieral  or  billowing  modifitnitions.  Inclnde  references  to 
test  standards.  te.st  specifications,  and  benchmark  lest  data.  uS  apprn|jriat.e. 
tiivc  specific  cnd4o-end  miming  examples  of  such  testing,  including  all  of 
tlie  job  ciintrol  code  rcijuircd, 

6.2  QA  Certification  Procedures 

I Gestalt  the'  t)mccdures  to  be  folh>wod  in  olitaining  QA  r<H*ertificalion  of 
all  chuiiges.  as  required  imder  ebiinge  control  restrictions. 

6.3  Special  Verification  Procedures 

Identily  and  give  prot'cdures  for  special  ai'ttvities  associatod  with 
rcccrtilication  of  the  software,  such  as  operational  demonstration, 
approvals.  Scaidiug  of  materials  to  the  program  library.  S|iecial  system 
protessor  registration  protncids.  etc. 
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7.  APPENDICES 

Aj)jK*iKHf(\s  may  iiiHiKle,  hnl  are  not  IfnUtcd  to,  explanutoiy  matcrfal  and 
pn>eodures  of  an  attxiliar)^  nature,  inserted  diroetiy  or  liound  separately  for 
eonvenienee.  rhe  following  topics  are  typical.  Appendices  may  l>e 
desitriiatefl  us  "Appendix  A/'  etc.,  if  desired,  rather  Hian  by  tlie  Dewcv- 
decimal  .system  u[iven  here. 

7.1  Glossary 

last  the  acroinfus.  inneinoni<'S,  abbreviations,  and  .specially  used  t<Tms 
that  iippoiir  in  this  tuauua),  and  give  a short  definit  ion  of  each. 

7.2  References 

Provide  a list  of  alt  source  docnrnents,  standards,  procedures,  and 
referonc'e  materia!  nstxl  for  program  maintenance.  Intlicate  the  subject 
matter  and  [>ur|>oso  of  each  nd’erence. 

7.3  input /Output  Formats 

Prr)>^ide  detailed  formats  and  .syjitax  tor  input  aiul  output  data  used 
specifically  In  software  maintenance.  Define,  a.s*  appropriate:  {0  data  ba,se 
I/O  formals,  parameters,  atul  control  characteristics:  [2^  cominnnic'ations 
dewice  I/O  format.s,  parameters,  aiwl  eontml  oharael (.'.rustics;  etc. 

7.4  Auxiliary  Tables 

Assemble  in  tafmlar  form  all  an.viliarv  reference  data  neederl  for  so  ft  wart: 
maintenance,  which  arc  liinter  located  in  an  appendix  rather  tiiaij  in  the 
text  proper.  Display  each  a.^:  a separate  siilwectioji  (7.d,f),  and  introduce  nr 
e.x plain  the  tise  of  eai.'h  talde  narratively. 

7.5  Summary  of  Procedures 

Pr{ivifle  an  aliluesdated  set  of  procedures  for  eadi  of  Hie  iiiaintenauce 
iiinctions  snitahio  tor  use  hy  tiuy  Icnowledgeablo  user.  This  suimnan'  should 
he  devoki  of  lengthy  tutorial  exjilanations,  <'ontuining,  instear),  only 
technical  descri|)tions  or  definitive  cxiimples  for  (piidc  ndcrence. 

7.6  Detailed  Examples 

Display  the  application  of  maintenance  pmt:odnres  via  samples  from 
bogiiming  to  end.  Show  all  input:,  indicate  all  interactions  in  timelv 
.scqneme,  and  display  all  resfionses  and  output; 


APPENDIX  L 

SAMPLE  PROGRAMS  FOR  PROJECT 
MANAGEMENT 


My  original  intent  for  thi;:  appendix,  while  1 was  writing  Part  I of  this 
work,  was  to  present  end-to-end  detailed  program  examples  tn  which  the 
standards  of  this  text  would  be  applied.  Such  programs  could  then  be  used 
JLS  examples  of  Sofnvarc  Specification  Documents  illustrative  of  Class  A 
and  B levels  of  detail.  1 had  hoped  to  enter  more  than  the  four  examples 
you  see  here,  Init  a coinpioinise  was  necessaiy'  for  reasons  of  space.  The 
programs  f envisioned  were  principally  management-oriented,  such  as 
Examples  L-1  and  L-4;  hut  design  aids,  such  :ts  Example  L-2,  and  useful 
subroutines,  such  as  Example  L-3,  were  not  to  be  left  out  altogether. 


The  programs  of  this  appendix  are  rather  small  and  based  on  well-known 
algorithms.  Neither  are  they  grandiose  in  range  of  application,  but  merely 
scratch  the  surface  of  project  management  and  development  needs.  More 
extensive  reqiiiremeiits  for  software  management  information  systems 
appear  in  [47j.  Useful  programs  for  grading  project  performance,  status 
reporting,  data  sorting,  and  linear  programming  appear  in  [48]. 


Small  programs  tend  to  have  limited  utility,  unless  they  can  easily  be 
generalized  to  wider  applications  than  usually  dictated  by  their  size.  I 
certainly  hope,  therefore,  that  the  standardized  developments  presented 
herein  are  both  sufficient,  structured,  modular,  and  understandable  ixs  to 
permit  such  extensions  to  be  easily  forthcoming.  However,  the  main  benefit 
of  this  appendix  more  probably  lies  in  using  the  given  examples  as  models 
for  documenting  programming  specifications, 
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1‘iiU‘li  of  the  examples  follows  the  SSD  outline  given  in  Appendix  E; 
however,  only  Evutiiple  L-1  goes  tlirotigh  a section-hy-scction  eonsidoration 
of  topies.  In  caeh  case,  headings  Hmt  did  not  apply  were  omitted;  in  some 
eiLses,  where  a tliooreticui  hudeground  neetlwi  to  he  establislied  for 
readahihty,  otlicr  headings  wore  invonterL 

Because  the  program  descriptions  are  not  directly  or  iiltlmatcly  coupled 
to  an  unumhiguous  computer  language,  I realize  that  some  readers  may 
pcissildy  interpret  what  tliey  reatl  here  slightly  differently  than  do  others. 
Nevertheless,  I have  tried  to  make  the  designs  as  free  c)f  language  or 
machine  (diaracterfstics  as  I consciously  could,  a*ul  I hope  the  iiitent,  if  not 
the  detail,  is  dear  in  each. 

"I'ho  first  example  (L.*l)  is  wliat  I consider  to  he  formal  Class  A detail 
with  respect  to  the  programming  spocifieatious  and  fairly  strict  adherence 
to  Appendix  E,  within  tlie  scope  of  tlie  host-independence  souglit  for.  Some 
areas  are  not  (juito  Class  A in  detail  and  need  to  lie  worked  on  liefore  one 
coutfi  tent)  the  whole  SSFD  as  “Class  A/*  !ti  this  sense*  the  SSD  is  seen  In  an 
embi'>x)nic  stage  of  dc\^elopmejit,  before  mudi  of  tlie  detailed  test 
spcciticatioiis.  etc.',  have  been  written.  Hie  level  jiresonted  may  seem 
“ovcrkiir  for  sudi  a*  short  program.  For  a large  program*  however*  such 
detail  may  he  essential  for  understanding* 

Examide  J*-2  is  a much  *shorter  program,  but  the  detail  love!  in  the 
programming  specification  is  still  Class  A*  within  lio*st-depciulent 
consid^^rations.  Stiindurds,  system  environment  and  interfaces*  test  and 
verifica  tion  details*  anri  other  lower-love!  considerations  are  not  covered*  so 
the  doi'ument  may  fall  into  the  Class  H eategoty\  in  that  “qualified 
personnel  (engineer  or  equivalent)  using  documented  tedmiques  and 
approved  prtigramnung  practices  may  be  retjuired  to  satisfactoril)'  jirodnce 
that  item  entirely  from  (nfonnation  supplied*’' 

Example  L-3  is  even  shorter,  yet  Class  A detail  prevails  in  the 
programming  specifitaitions. 

Hie  final  example*  l -d*  is  Class  B;  the  level  of  detail  in  the  programming 
s*pe;eificaMon  sc(»tion  relies  on  the  programmer  s ability  to  design  tlie  code 
effectively*  with  discretion  permitted  if  there  is  satisfaction  of  the  program 
reciiiiroments  with  respect  to  performance  and  quality  without  unreason- 
able risk 
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EXAMPLE  L»1 

GENERATING  SCHEDULES  USING 
THE  CRITICAL  PATH  METHOD 


1.  INTRODUCTION 


1.1  Purpo^  and  Scope 

This  specification  covers  the  design  of  a program  to  accept  items  from  a 
project  Work  Breakdown  Structure  (WBS)  to  compute  schedule  informa* 
tion,  such  as  critical  path  status,  earliest  starting  time,  latest  start  time, 
earliest  finish  time,  latest  finish  time,  and  float  (or  slack)  time  for  each  task, 
and  to  print  a schedule  based  on  these  computations. 

The  program,  in  the  form  specified  here,  does  not  recognize  precedence 
of  tasks  based  on  resource  availability,  nor  does  it  allow  explit.u  usage  of 
lag  times,  starting  dates,  or  ending  dates  to  be  input  by  the  user,  as  some 
PERT/CPM  systems  do.  Lag  times  may  be  simulated,  however,  as  separate 
tasks  appropriately  inserted  into  the  network. 

1.2  General  Description 

The  basic  criticabpath  method  of  schedule  network  analysis  employed 
here  is  discussed  in  several  sources;  References  7.2,1  and  7.2.2  are 
recommended  to  the  interested  reader.  Extensions  to  the  biisic  method 
appear  in  many  PERTdike  systems,  such  as  the  IBM  Projec  t Control  System 
(Reference  7.2,3). 

The  capability  described  herein  assumes  that  work  task  identification, 
task  duration,  and  task  precedence-successor  relationships  are  input  from  an 
unspecified  medium  into  memory  for  access  by  the  computation  modules. 
Results  of  computations  are  printed  on  a linC'Oriented,  paged-output 
device. 

Further  details  regarding  the  function  of  the  program  are  contained  in 
Section  4,  and  programming  specifications  appear  in  Section  5. 


2.  STANDARDS  AND  CONVENTIONS 


2.1  SpecificatiDn  Standards  and  Conventions 

Specifications  contained  herein  .shall,  on  completion  of  this  document, 
reflect  A-l  documentation  quality,  as  defined  in  Reference  7.2.4.  Flowcharts 
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iind  :u'forn[3an\ing  narrative,s'  lire  usetj  to  ck'fint'  tlio  progriunmitig 
spiH'ifUrations  (S<.K:t  iou  5^:  those  are  govemerl  by  Hofcronee  7,2.5. 

2.2  Programming  Standards 

Programming  stanflards  ns  speeified  in  Heferenee  7,2.0  shall  apply  to  all 
implementations  except  as  othem  ise  dispensed  by  waivers  stated  iierein, 

2.3  Test  and  Verification  Standards 

Tests  aiid  verifieatitm  acHvities  are  governed  by  Uererenee  7,2.7. 


2.4  Quality  Assurance  Standards 

QA  standard.s’  as  dcRncd  by  Uot’erence  7.2.S  and  further  reiiued  in  Secaiou 
0.3  sliall  apply  as  cundition  for  deliveiy. 

3.  ENVIRONMENT  AND  INTERFACES 

lliis  specification  is  meant  to  be  system-independent  in  the  .s'ense  that  it 
places  few  restrictions  on  periphorul  devices  and  memory,  except  that 
an  input  medium  nmst  lie  available  to  input  the  WHS  network:  (2^ 
suflicient  storage  is  available  for  holding  tbe  network  and  the  program:  and 
(3^  an  tmtput  device  is  available  lor  displaving  the  schedule  inlormation.  II 
insniht'ient  fast  storage  is  available  for  the  network,  but  random-access 
mass  storage  is  available,  then  suitable  alterations  in  tl^e  program  can  be 
made  to  at  commodatc  such  a configuration. 

'Phe  coding  langnage  is  al.so  unspecified;  however,  tiu'  pi'ocedui’at 
descriptions  used  presnnte  that  strings  of  characters  viin  he  input  and 
mit)>nt,  and  ill  at  such  strings  can  be  specified  by  name,  or  by  name  and 
index  value,  if  arraved.  Coding  in  lower-level  languages  not  possessing 
string  operations  must  simulate  llicse  features  as  .subroutino.s  or  functions. 

4,  SOFTWARE  FUNCTIONAL  SPECIFICATION 

4.1  Functional  Organization  and  Overview 

A task  in  a W ork  Breakdov^  n Structure,  ;ts  assumed  b\*  this  program,  is 
specified  by  tO  a task  code,  (2^  a task  description,  a duration,  and  (4^  a 
list  of  codes  of  tasks'  that  must  terminate  before  the  current  task  may 
initiate  (for  reasons  decided  by  the  userV  No  task  may  initiate  until  all  of  its 
named  prct‘cding  tasks  have  terminated.  Special  tasks  with  ’/ere  duration 
mav  he  inserted  (tliose  are  called  ’‘milestones'*^  so  as  to  enable  the 
definition  of  schethde  networks  in  which  tu,sks  may  start  syiu  hronously  (a 
start'to-start  relationsliip^  or  terminate  syntdironously  at  a milestone  (an 
end-tO“ond  relationship),  in  addition  to  the  normal  precedences  (end-to-start 
relationships). 
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The  mrliciit  start  of  a task  is  defined  as  the  ituixhnuin  earliest  finish  of  all 
the  liste<l  required  prior  tasks;  the  eorlust  fiuish  of  a task  is  defined  as  its 
earliest  start  phis  its  duration.  The  latest  finish  of  a task  is  defined  as  the 
niininnmi  latest  start  of  all  listed  required  suhsequent  tasks:  tlie  latest  start 
is  the  latest  finish  less  the  task  duration. 

One  special  milestone  (zoro-duriition  task^  must  he  identified  us  the 
"'starting"  task,  having  uo  list  of  [ireceding  task  codes:  this  task  also  has  a 
"'starting  date"  defined.  A ""project  termination"  milestone  is  optional, 
supplied  by  the  program,  if  omitted:  the  earliest  start  and  latest  finish  of 
this  task  are  set  equal. 


'rhe  float,  or  slack  time,  of  a task  is  defined  as  the  difference  lietween  its 
latest  and  earliest  start.  A task  with  zero  float  is  said  to  l>e  a critical  (ask 
I’here  always  exists  at  least  one  set  of  critical  tasks  that  span,  end-to-ond, 
tlic  entire  project;  these  tasks  are  said  to  form  a critical  path  in  the  [project 
workload.  Ciitical  path  tasks  are  indicated  on  the  printout  hv  an  asterisk 


If  a critical-path  task,  slips  in  sdiediile.  the  project  termination  date  slips 
an  equal  amount.  Any  non-critical  task  may  slip  by  an  amount  up  to  its 
float  without  cansing  end<date  slippage. 


The  input  unit  of  all  durations  is  whole  dmjs.  Output  schedules  then 
account  for  normal  work  week  and  holidays  by  way  of  a calendar  data  base 
residing  in  an  unspecified  sequential  file  mediutn  (e.g..  disk  or  cardsl  The 
output  schedule  consists  of  a list  of  tasks  sorted  in  I oj)o logical  order,  giving 
early  and  late  start  and  finish  dates,  plus  the  float  time,  in  addition,  early 
and  late  start  and  finish  days  of  work  since  project  start  are  displayed  on  the 
printout,  with  critical  tasks  identified. 

4. LI  Detection  of  and  Reetivery  From  Sysieni  Failure 

This  specification  does  not  address  system-dependent  features  of  the  host 
environment, 

4,  L2  Detection  of  and  Hesponsv  to  Data  Input  Errors 

This  specification  does  not  cover  syntactic  checking  of  data  elements 
read  from  the  work  breakdown  stnicture  or  calendar  file.  Such  checking, 
however,  shall  be  incorporated  into  the  input  functions  of  the  jirograin  thtit 
read  the  pertinent  data  described  herein.  Such  functions  shall  emit 
diagnostic  error  messages  that  describe  the  syntactic  violation,  and  shall 
then  operate  as  if  an  end-of-file  had  appeared. 
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4.2  Configurations  and  Modes 

The  program  described  herein  luis  only  a single  mode  of  operatioiK 
witliont  options.  Consult  Section  7.3  for  suggested  future  options. 

Input,  Processing,  Output  Specifications 

Mai.'v  of  the  formats  for  input  data,  as  well  as  other  matters,  are  left 
somewhat  open,  to  permit  flexihility  in  implementations  on  host  systems 
with  diifering  charactoristies.  Such  matters  may  he  resolved  arbitrarily,  so 
iQUg  the  results  do  not  conflict  with  other  specifications  contained 
herein. 


lnj>uts  to  the  program  are  as  follows: 

a.  For  the  project  start  (the  first-receiveti  task,  with  no  prodcci^ssors); 


milestone  code 
milestone  title 
start  date 


string  of  characters 
string  of  characters 
day  of  year 


The  input  fonnat.  date  format,  and  string  ler.gths  are  not  covered  by 
this  specihcatioiu  Fhc  output  format  specified  in  7.5  provides  space 
for  displaying  up  to  10  and  32  characters,  respectively 

b.  For  each  task,  from  the  same  medium  as  (a),  above: 


task  code 
task  title 
duration,  in  days 
list  of  precedent* 
task  cckIcs 


string  ut  characters 
string  of  characters 
integer 

task  codes,  above 


The  input  medium,  mode  of  entr\\  and  format  of  these  items  are  not 
covered  liy  this  SSD,  Milestones  (except  start)  are  input  as  tasks  with 
zero  duration, 

c.  From  the  calendar  file,  for  each  day  in  sequence,  extending  over  the 
entire  project  lifetime: 

workday  boolean 

date  month,  day,  year 

The  actual  detailed  configuration  and  format  of  these  data  are  not 
covered  by  this  specification. 

Although  precise  input  details  have  been  excluded  from  tlie  above  items, 
the  programming  specifications  of  Section  5 do  show  definitive  require- 
ments for  order  of  input  and  data  type. 
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Two  task  codes  are  reserv  ed.  Those  are: 

END 

FINISH 

The  END  tusk  code  is  a signal  to  the  program  that  there  are  no  further  tasks^ 
the  network  data  is  complete.  The  end  record  is,  therefore,  the  last  in  the 
WBS  file.  An  attempted  read  resulting  in  endfile  shall  return  “end'*  as  the 
item. 

The  FINISH  task  code  is  used  internally  within  the  program  to  name  the 
project  termination  milestone.  No  title  is  supplied  for  this  milestone  by  the 
prograju.  The  user  may  use  finish  as  a task  code  and  supply  a title; 
however^  any  task  naming  FINISH  as  a predecessor  will  lie  flagged  as  an 
error.  Successor  linkages  to  FINISH  will  be  erased  by  the  program. 

Processing  specifications  for  the  program  are  as  follows: 

a.  Accept  Sturt  milestone  and  task  descriptions,  as  above.  The  first  task 
encountered  is  assumed  to  be  the  start, 

b.  Topologically  sort  the  tasks  (Reference  7,2.9)  into  a list  in  which  all 
precedent  tasks  for  a given  tusk  precede  that  tusk  in  the  list. 

c.  Scan  this  list  (it  begins  with  the  start  mitestone),  computing  start  and 
finish  times  (defined  in  Section  4,1,  above)  for  each.  Identify  critical 
tasks. 

d.  Detect  and  display  errors  in  improperly  formatted  input,  insufficient 
calendar  input,  and  circular  m*  disconnected  networks, 

e.  Print  the  schcriule. 

Output  from  the  program  consists  of  the  schedule  report  and  error 
diagnostics.  The  output  schedule  takas  the  form  of  a report  which  lists  the 
tasks  in  topologically  sorted  order,  showing  eurty/late  start/finish  dates, 
flout  values,  and  times  past  project  start.  The  output  format  is  shown  in 
Figure  7,5.1, 


5.  PROGRAMMING  SPECIFICATIONS 
5.0  Program  Overview 

The  SCHEDULER  program  consists  of  four  subprograms  that  execute  in 
sequence: 


422  Appendix  L 


BUILD  NETWORK  (build) 

TOPOLOGICAL  SORT  (toposort) 

CALCULATE  DATES  (dates) 

DISPLAY  SCHEDULE  (display) 


The  representation  of  the  schedule  network  within  the  design  is  the  chief 
item  required  for  understanding  the  procedures  in  the  remainder  of  this 
section.  There  is  a certain  set  of  information  that  is  input  or  calculated  for 
each  task*  represented  by  a node*  in  the  network: 


information 

identifier 

type 

TASK  CODE 

CODE 

string 

TASK  TITLE 

TITLE 

string 

TASK  DURATION 

DUR 

integer 

EARLIEST  START 

EST 

integer 

EARLIEST  FINISH 

EFIN 

integer 

LATEST  START 

LST 

integei 

LATEST  FINISH 

LFIN 

integer 

FLOAT  TIME 

FLOAT 

integer 

NUMBER  OF  PREDECESSORS 

COUNT 

integer 

POINTER  TO  LIST  OF 

TOP 

“pointer" 

SUCCESSORS 

The  first  three  items  are  input  directly,  the  next  six 

are  calculated  after 

sorting,  and  the  final  is  supplied  as 

a result  of  building  the  network.  The 

node  data  stmeture  and  network 

relationships  are 

organized  into  a 

simulated  list  using  arrays  named  with  the  identifiers  listed  above,  along 

with  the  two  arrays: 

information 

identifier 

type 

SUCCESSOR  NODE 

sue 

“node’’ 

NEXT  LIST  ITEM 

NEXT 

“pointer" 

The  ‘‘pointer"  data  type  in  the  two  tables  abc^ve  is  an  integer  index  into 
the  SUCiNEXT  arrays;  the  “node"  data  type  is  an  integer  index  into  the 
CODE : TITLE TOP  arrays.  In  this  way,  information  about  a node 
(task)  is  locatable  via  the  node  index,  and  its  successor  nodes  can  be  found 
following  the  node  top  pointer  to  sue,  for  the  first,  and  thence  via  NEXT 
pointers  to  the  remainder.  This  representation  is  discussed  further  in  Knuth 
(Reference  7.2.9).  The  apparent  node  representation  is  shown  in  Figi>re 
5.0.1;  the  network  is  implicit,  then,  in  COUNT  and  sue  relationships. 

Languages  that  hav-e  “ARRAY  OF  RECORD"  syntax  may  code  each  node 
as  an  indexed  record. 


f=jguTe  5.0,1.  A simpfo  prececfencd  graph  and  tts  structural  representation 
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5.0. 1  Building  and  Sorting  the  Network 

rhe  process  of  building  tlie  network  consists  of  reading  the  WHS  file  and 
storing  task  information  in  the  node  arrays.  As  tasks  arc  read,  each  task 
index  is  recorded  in  an  Integer  topological-sort  list  array.  Tsort.  Indexes  of 
nodes  having  a zero  predecessor  COUNT  are  qiicncd  into  TSOnr  from  the 
front;  these  are  alrearly  in  sorted  order.  The  others  are  queued  at  the  rear  of 
TSORT,  Such  a list  permits  the  processing  of  tasks  independently  of  the  way  the 
search  algorithm  has  entered  the  nodes  into  meinor>\  Thereafter,  the 
topological  sort  procedure  considers,  in  turn,  each  node  in  the  front 
segment  of  TSORT,  “removing  its  edges"  in  the  iictwork  by  reducing  the 
COUNT  of  nodes  identified  as  successors.  When  a COUNT  field  of  a node  hits 
zero,  that  node  index  is  inserted  at  the  rear  of  the  front  segment  of  TSORT.  If 
.some  nodes  still  have  non-zero  counts  after  all  of  the  front  segment  of 
TSORT  has  been  processed,  a loop  in  the  network  exists  (identified  as  an 
error). 

5.0. 2  Calculating  Schedule  Times 

Early  start  and  finish  times  are  calculated  by  scanning  the  nodes  listed  in 
TSORT  in  forward  order;  then  late  starts  late  finish,  and  float  values,  by 
scanning  Tsort  in  reverse  order. 

Dates  are  assigned  to  the  project  times  by  way  of  the  C.AEonDa/?  array, 
filled  from  the  calendar  file.  The  caldr  array  is  an  ordered  set  of  strings 
indexed  by  work  day.  More  prccLsoly,  when  filled,  the  value  of  caldR(O)  is 
the  starting  date  ( month / d ay /yea«)  corresponding  to  START,  read  in  from 
the  project  start  milestone,  start  is  an  integer  that  defines  the  day  of  year 
for  beginning  the  calendar  file  read-in.  The  size  of  the  caldr  array  permits 
entries  indexed  0 through  maxdate.  If  the  project  goes  hevnncl  maxdate  days, 
only  the  first  maxdate  clays  appear  in  the  array.  If  the  calendar  file  doCsS  not 
extend  far  enough  into  the  future  to  provide  dates  for  the  project  times, 
then  “day  n“,  where  n is  the  project  work  day,  is  entered  into  the  CALDR 
array. 

Further  details  are  contained  in  the  programming  specifications  in  the 
remainder  of  this  section. 
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5*0.3  Program  Tier  Chart 

The  list  below  presents  the  modular  nesting  of  program  elements: 

1 SCHEDUUefI 

. 1 INITIALIZE 

. 3 HEADEFLBATA 
. 2 BUILD 

. 6 REGISTER 

. 1/SI  SEARCH 
. 6 CONNECT 

. 3/SI  SEARCH 
.7/El  ERROR 
. B TERMINATOR 

.1/SI  SEARCH 
, 3 CHECK-SUCCESSORS 
,3/El  ERROR 
, 6 LINK_TO_FINISH 
.4/El  ERROR 

, 5 TOPOSORT 

. 4 ERASE-EDGES 
. 7 DIAGNOSE 

.t/El  ERROR 

. 7 DATES 

. 1 EARLY-DATES 

, 4 SUCCESSOR_DATES 
. 3 LATE-ANO-FLOAT 

, 4 TASK-LATE-DATE 
. 8 DISPLAY 

. 1 CALENDAR 

.1,2,  10/El  ERROR 
.67  FI  STR 

El  ERROR 

FI  STR  (integer-to-strlng  conversion) 

SI  SEARCH 

10/Et  ERROR 

Indentation  in  this  list  denotes  procedural  nesting  of  the  modules  named. 

Numbers  are  Dewey-decimal  module  codes  (e,g.,  TERMINATOR  is  found  as 
module  1.2.8). 
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Chart  Number 

1 

Module  Name 

SCHEDULER 

Date 

4/1/77 

5.(1)  Critical-path  SCHEDULER  program 

.1  Declare  global  schedule  network  arrays  and  set  all  numeric  items 
to  zero,  all  string  items  to  null.  Prepare  the  header  data  for  the 
report  in  step  8. 

,2  Tn  Iniilding  the  network  if  either  the  task  node  arrays  or  the 
successor  linkage  arrays  liccome  filled  prematurely*  print  an  error 
message*  *\dd  a project  termination  milestone  to  the  schedule 
network*  Return  g flag  OVFLOW  with  false  value  if  the  VVBS  input  did 
not  exhaust  the  network  arrays;  true,  otherwise*  NTASKS  records  the 
number  of  tasks  entered. 

.3  A true  value  of  Ovflow  terminates  the  scheduler, 

A printiug  a me.ssage  before  the  program  terminates* 

.5  If  the  network  was  input  without  overflow,  then  the  TSORt  list 
contains  the  topological  sort.  If  the  network  contains  a loop,  print 
"WBS  IS  CIRCULAR  AMONG  ITEMS'*  and  give  the  list  of  task  codes.  Identify 
one  such  loop.  T records  the  number  of  sorted  items  entered  into 
TSORT* 

.6  If  all  ta*sks  are  not  in  the  list,  the  WBS  i*s  circular,  so  terminate. 

.7  Otherwise,  scan  the  list  forward  for  early  times  Csee  definitions  in 

Section  4*l),  and  in  reverse  for  late  times  (Section  4.  l).  Calculate  float 
tiinc.s  during  the  second  scan  as  well. 

.8  See  Sections  4.3  and  7.5  for  details  of  output  format  and  content 

,9  Perform  any  cleanup  necessar,  in  the  coding  language  (e.g.,  dosing 

files)  before  program  termination. 
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i. 

PRINT 
•SCHEDULER 
TERMINATED ' 


^ SCHEDULER^ 


SCHEDULER 
I APR  77 


INITIALIZE 


DECLARE  AND 
EMPTY  NETNORk' 
ARRAYS 


BUILD 


INPUT  HBS. 

ovflow=tkue  if  1 

TOO  BIG 


E3 
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Chiirt  Nuinl>or 
Module  Name 
Date 


1,1 

INITIALIZE 
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5.(11)  INlTtAUZE  the  scheduler  program 

On  entry,  no  data  clodarattons  have  been  made. 

This  procedure  declares  all  data  for  the  entire  prograiiK  dears  the 
schedule  network  by  setting  all  numeric  values  to  zero,  ail  strings  to  null, 
and  stores  the  information  necessar)^  to  generate  the  top  of  tlic  schedule 
report  in  header  for  later  access  by  display/  1,8, 

On  exit,  the  prograTO  is  read}'  for  execution. 

.1  All  data  declared  as  specified  here  is  assumed  globally  available  to 
all  modules  in  this  program.  I’hcse  are  placed  all  together  so  as  to  lie 
statically  allocated  at  compile  time,  should  the  coding  language 
demand  it;  those  arc  placetl  first,  la  case  declarations  arc  executable. 
In  asscrnldy  language,  it  may  he  iiecessaty  or  desirable  to  locate  the 
code  for  such  declarations  elsewhere. 

,2  Strictly  speaking,  only  est,  count,  and  TOP  imcsl  be  cleared;  code, 
TITLE,  and  DUR  are  later  input,  efin,  est,  lst,  lfin,  and  float  are 
computed,  sue  and  next  need  not  be  cleared,  either;  however,  later 
modifications  nuiy  change  some  of  these  imsumptions.  Therefore, 
dear  them  all. 

,3  VfEAOER  infonnatinn  prepared  at  this  poiiU  is  used  by  the  display 
step  1.8.7  to  achieve  the  format  in  7.5, 

Initialize  I/O  media  as  required  to  input  VVBS  azid  calendar  data  in 
later  part.s  of  the  program. 
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Chart  Ntunher 
Module  Name 
Date 
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HEADER^DATA 
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5.{1.1.3)  Generate  HEADER  DATA 

The  module  described  here  at  prescut  is  a STUB. 

On  entry,  data  structures  have  been  declared. 

This  procedure  ol>tains  infoniiatioii  from  au  input  tnccliuin  for  use  iu 
printing  the  output  header. 

On  exit,  the  striitg  header  contains  the  title  to  be  used  in  the  first  line  of 
the  schedule  report  (see  7.5). 

Rationale:  Decisions  regarding  exact  input  format  have  not  been  made. 
'Fhese  decisions  will  l)c  influenced  by  choice  of  prograiUTning  language  and 
possible  interaetive/batch  operating  modes.  These  decisions  affect  only  the 
DT:splay  step  L8.7,  and  may.  therefore,  be  postponed  until  the  other 
algorithms  herein  are  verified. 
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Chart  Number  1.2 

Module  Name  BUILD 

Date  4/4/77 

5.(1^)  Procedure  to  BUILD  schedule  network 

Oil  enir>',  the  schedule  netu^ork  has  been  declared,  but  cleared. 

Tills  prueediire  inputs  the  VVBS  information  and  builds  the  schedule 
network  as  described  in  Section  5.0. 

On  exit,  the  network  has  been  formed.  CODE,  title,  dur,  count,  and  TOP 
arrays  contain  the  appropriate  values,  and  sue  and  next  arrays  register 
successors,  so  us  to  simulate  list  format  ntasks  contains  the  number  of 
tasks  identified  in  the  WBS. 

.1  AVAIL  points  to  the  next  available  suC:Next  pair  to  record 

successors.  NTASKS  is  the  Ahimber  of  TASKS  input.  MORE  is  a boolean 
to  control  looping  in  steps  2 through  6,  below,  T is  the  integer  index 
of  the  TSORT  list  (empty).  B locates  the  bottom  of  the  unsorted  list  in 
TSORT  (also  now  empty),  ovflcw  indicates  that  the  network  is  not  full. 

.2  MORE  remains  true  while  there  arc  tasks  to  be  input. 

,3  TASKCODE  is  the  first  field  on  the  input  line. 

A An  “END**  signals  there  are  no  more  tasks, 

.5  thus,  terminate  the  iteration  when  “end  " appears, 

.6  As  long  iLs  there  are  btsks,  however,  put  these  into  tJie  network.  If 
there  is  no  room  in  the  node  (i.c.,  task)  arrays,  signal  ''task  overflow" 
error,  fi  this  task  cau.ses  overflow  of  the  successor  linkage  arrays, 
signal  "linkage  overflow''  error. 

,7  If  there  wits  no  overflow, 

,8  add  a termination  milestone  to  the  schedule  nchvork,  if  needed, 

, linked  as  the  successor  to  all  tasks  not  having  an  e.vplidt  successor 
identified. 
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Chart  Number 
Module  Name 
Date 


1.2.6 

REGISTER 

4/11/77 


5.(1.2.6)  REGISTER  tasks  into  network 

On  euir)%  taskcode  (string)  contains  the  first  field  of  the  input  record 
corresponding  to  a task,  task  (integer)  and  morepred  (boolean)  have  been 
declared,  but  do  not  contain  pertinent  information.  The  schedule  network  is 
cither  empty  or  partially  completed,  ovflow  is  global  and  false.  The  input 
medium  is  positioned  just  past  the  taskcode  field  of  the  current  record. 

This  procedure  enters  the  task  descrilicd  on  the  input  current  record  into 
the  schedule  network,  if  possible. 

On  exit,  the  task  has  been  recorded  into  the  network.  If  any  tasks  have 
been  input  with  no  predecessors  named,  these  tasks  are  entered  into  the 
TSORT  list  (the  first  is  presumed  to  be  the  project  start  milestone),  OVFLOW 
and  MORE  will  be  toggled  on  error,  and  ‘'TASK  overflow''  printed.  T is  the 
maximum  index  of  tasks  put  into  the  TSORT  list  that  are  already  in  sort  (no 
predecessors).  The  remainder  of  task  indexes  is  inserted  into  TSORT  from  B 
to  MAXTASKS,  to  aid  in  later  setuming  for  the  terminator. 

.1  SEARCH  the  network  for  the  input  TASKCODE  identifier.  If  found, 

return  its  index  in  TASK;  if  not  found,  insert  it  into  CODE  at  a blank- 
location,  and  return  the  index  in  TASK.  Set  NTASKS  to  record  the 
current  iVuinber  of  registered  TASKs.  Set  OVFLOW  true,  MORE  false  on 
overflow,  and  print  the  error  me.ssage  “task  overflow". 

.2  When  there  is  room  for  the  task, 

.3  input  the  title  and  duration,  and 

.4  prepare  to  read  list  of  predecessors  l\y  setting  the  moreprED  flag  true, 

.5  Then  while  there  are  predecessors  on  the  record. 

.6  CONNECT  these  into  the  network  by  attaching  a successor  identifying 
this  TASK  to  each  named  predecessor,  ff  the  successor  array  is 
depleted,  set  OVFLOW  true  and  print  “LINKAGE  OVERFLOW'".  Set  MORE  and 
MOREPRED  false  to  terminate  processing.  Increment  the  count  for  this 
TASK  for  each  predecessor. 

.7  However,  if  no  predecessor  was  indicated,  then 

,8  enter  this  task  into  bottom  of  the  TsoRT  list,  as  tiiese  tasks  are  already 
sorted. 

.9  The  other  tasks  are  inserted  at  the  top  of  the  TSORT  list  to  keep  track 
of  them  for  TERMINATOR  (module  1.2.8). 
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Chart  Number  1.2.6,6 

Module  Name  connect 

Date  4/11/77 

5.(1.2.6.6)  CONNECT  tdsk  into  schedule  network 

On  entry,  the  TASK  has  been  located,  and  its  title,  duration,  and  code 
have  bec!i  entered  into  their  corresponding  array  elen^ents;  reinainiiig  fields 
in  the  input  record  arc  predecessor  task  codes,  morepred  Is  true,  expecting 
such  predecessors. 

This  procedure  extracts  these  task  codes,  looks  them  up  (inserting  them 
into  the  network  if  not  previously  there),  and  causes  a linkage  tetween 
prc<leccssor  tasks  and  the  current  task  by  sue.  NEXT  pairs.  Error  messages 
appear  and  OVFLOW  and  MORE  are  toggled  on  overflow. 

On  exit,  all  named  predecessors  will  have  been  linked  to  the  current 
TASK,  and  the  number  of  predecessors  will  appear  in  the  COUNT  for  that 
TASK,  MOREPRED  will  be  false  when  the  list  of  predecessors  hits  been 
exhausted 

.1  Tr>'  to  read  a predecessor  task  code  into  the  PRED  string;  however, 
:f  no  predecessor  is  there,  set  MOREPRED  false  to  terminate. 

,2  If  there  is  a predecessor  code  named, 

,3  look  up  its  index  PTASK  (responding  to  overflow  if  necessarv'). 

.4  If  there  was  no  overflow, 

.5  and  if  there  is  still  room  in  SUC:  next  arrays, 

,6  the!i  link  the  current  task  as  a successor  to  the  predecessor  tiisk, 

.7  If  there  is  no  room  in  sue*,  next,  emit  the  error  message,  and 

,8  set  flags  necessary^  to  terminate  operations. 

.9  If  there  is  a task  overflow,  its  nmssage  will  have  been  printed  by 
SEARCH.  Hence,  merely  reset  morepred  to  terminate  operations. 
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Chart  Number  1.2.8 

ModuLe  Name  terminator 

Date  4/ M/77 

&(1.2.8)  Attach  project  TERMINATOR  to  network 

On  cntry\  the  schedule  nct\vork  has  been  built,  except  that  uo  project 
termination  may  have  been  provided,  tsort  from  1 t(5  T contaias  sorted 
task  indices;  from  B to  maxtasks.  tsort  has  recorded  t)ie  other  tasks,  avail 
ptiints  to  the  next  available  suc:  next  pair. 

This  procedure  creates  sue-.  NEXT  pairs  and  attaches  them  to  eveiy^  task 
not  having  any  identified  successo/’s.  If  this  causes  an  overflow,  the 
appropriate  error  message  appears.  By  sequencing  through  tasks  as  listed  in 
TSORT,  this  algorithm  is  independent  of  the  assignment  of  indices  to  tasks  by 
SEARCH/Sl. 

On  exit,  the  .schedule  network  is  complete,  unless  OVFLOW  has  been  set 
true.  The  only  task  with  no  successor  is  the  added  termination  node, 

.1  Find  the  '‘finish*’  task  as  task,  or  enter  it  into  the  network 
(responding  to  overflow  if  necessiuy'),  returning  task.  Set  ovFLOW  true 
and  print  “task  overflow"  if  unsuccessful, 

.2  II  there  is  no  overflow  (ovflow  false), 

.3  assure  that  this  TASK  has  no  successors  named  by  user.  Inform  user  of 
erroneous  asugc,  if  detected,  by  printing  the  successor  task  code  list. 

A Make  a milestone  of  task.  The  TITLE  is  not  altered  (null  if  no  title 
supplied).  Save  the  finish  milestone  successor  list  top  pointer  (it 
should  be  nil),  and  change  it  to  a nomnil  value  to  prevent  a successor 
linkage  from  being  attached  in  step  6,  below,  (top  (TASK)  will  be 
restored  later  in  step  8),  Initialize  i to  range  through  all  tasks, 

.5  Loop  through  all  tasks:  fir.st>  the  ones  already  in  sort,  and  then  the 
remainder.  These  are  listed  in  the  tsort  array  from  1 to  T and  B to 
MAXTASKS, 

,6  Examine  each  task;  if  its  top  is  nil,  it  has  no  successors,  so  get  a 
SUC:  NEXT  pair  and  link  this  task  to  the  FINISH  milestone,  Set  OVFLOW 
true  if  no  such  linkage  can  be  made.  If  TOP  is  noii-nil,  take  no  action. 

.7  Setting  I to  the  “next"  value  is  incrementing  by  1 except  when  I 
goes  beyond  T,  whereupon  the  “next”  value  is  B,  See  step  5, 

,8  Reset  the  top  of  the  termination  milestone  to  indicate  it  has  its 
previous  succes.sors  (it  was  changed  in  step  4),  In  the  anomalous  case 
where  this  milestone  has  successors,  this  procedure  will  have  created 
a cycle  of  tasks,  which  will  then  be  detected  by  DIAGNOSE/ 1.5. 7, 
Restoring  TOP  is  necessary  for  correct  diagnostic  operation. 
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Chart  Number  1.2.8.3 

Module  Name  chec»c,successors 

Date  4/11/77 

5.(1.2,8.3)  CHECK  SUCCESSORS  of  finish  milestone 

On  entry,  the  finish  task  has  been  identified  as  TASK. 

This  procedure  prints  a list  of  task  codes  that  listed  the  finish  task  code 
as  a predecessor. 

On  e.vit,  the  data  space  is  not  altered. 

.1  The  Pointer  p,  if  non-ntl,  indicates  that  FINISH  has  appeared  as  a 
predecessor  code  of  at  least  one  task. 

.2  While  there  is  a list  of  successors, 

.3  inform  the  user  of  the  erroneous  usage, 

A advance  to  the  next  successor,  and  repeat. 
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Chart  Number  1. 2.8^6 

Module  Name  link_to„finish 

Date  4/12/77 

5^(1.2*8i6)  LINK  a task  without  successors  TO  the  FINISH  task 

On  entry,  i is  the  Index  of  the  TSORT  list  of  tasks  where  a task  TOP  is  to 
be  examined. 

This  procedure  attaches  a SUC:  NEXT  token  to  the  TOP  of  the  tsgrt  ( I) 
task,  if  TOP  is  nil  for  emits  an  error  message  and  sets  QVFLOW  true  if  AVAIL 
has  been  exhausted!),  pointing  to  the  finish  task* 

On  exit,  the  tsort(I)  task  is  liriked  to  the  FINISH  milestone  if  it  had  no 
successor,  or  else  OVFLOW  has  been  set  true. 

.1  TSORT(i)  is  a task,  so  its  TOPj  if  nib  indicates  that  the  task  had  no 
stated  sueeessors. 

.2  Therefore,  if  there  is  a SUC:  NEXT  pair  available, 

.3  attach  the  termination  milestone  as  the  successor  to  the  TSORT(I) 
task. 

.4  But  if  there  is  no  more  room,  output  the  error  message,  and 
.5  indicate  that  overflow  has  occurred. 
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Chart  Number  1.5 

Module  Name  tgpgsobt 

Date  4/12/77 


&(1^5)  TOPOIogIcal  SOFIflhg  of  tasks 

On  entry,  the  network  has  been  built  The  TSOBT  list,  which  will  contain 
the  sorted  tasks,  has  all  tasks  with  no  predecessors  already  in  the  list,  in 
positions  1 through  T (the  Tail  of  the  listl 

This  procedure  adds  the  remaining  tasks  to  tsort  in  topologically  sorted 
order,  unless  the  schedule  network  contains  erroneous  circular  task 
requirements.  In  this  latter  case,  the  set  of  tasks  not  in  the  list  and  one 
schedule  circular  path  are  identified. 

On  exit,  the  COUNT  array  will  have  been  destroyed.  If  an  error  was 
present  in  the  schedule,  the  value  of  T will  be  less  than  NTASKS,  which  wilt 
cause  SCHEDULER/!  to  bypass  the  generation  of  the  schedule. 

.1  F indexes  the  TSQRT  array  from  the  TVont 

.2  Iterate  ^vhile  there  are  tasks  in  the  tsgrt  list  which  have  not  had 
their  successor  edges  '"removed. ” 

,3  p after  this  step  Foints  to  the  suc:  next  list  for  a task  which  has  no 
predecessors,  or  has  had  its  predecessors  “removed**  in  a previous 
iteration. 

A Reduce  the  COUNT  field  of  all  successor  nodes  of  this  Front  task. 

,5  Having  exhausted  the  successor  list  for  a given  task,  advance  the 
Front  of  the  TSORT  list  to  unqueue  the  next  zeto-predecessor  task 
during  the  next  iteration  (step  2,  above).  Cycling  does  not  occur  when 
F goes  beyond  T. 

.6  If  the  number  of  tasks  deposited  iii  TSORT  is  not  equal  to  the 
number  of  tasks  entered  into  the  program,  then 

,7  print  a diagnostic  message,  '-Wes  has  at  least  one  gVgle  among 
tasks’*,  followed  by  a list  of  task  codes  not  in  the  TSORT  list  Then 
determine  and  print  one  such  cycle  of  tasks. 


':;5 
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Chart  Number  L5.4 

Module  Name  erase_edges 

Date  4/12/77 


5i(1.5.4)  ERASE  EDGES  to  successor  nodes 


On  on tiy,  P has  been  set  to  the  TOP  field  of  the  TSORT  (F)  task,  F being 
the  index  into  the  Front  of  the  TSORT  list  of  node  indieesi 


This  procedure  iterates  through  the  SUScessor  list  of  the  TSORT  (F)  task, 
reducing  the  CQUhlT  field  of  each  successor  node. 

On  exit,  the  COUNT  fields  of  all  successor  nodes  of  the  F^ihdexed  TSQrt 
will  have  been  reduced  by  one, 

,1  Initiate  an  iteration  for  the  current  front  task,  and  maintain  this 
iteration  while  this  task  has  successors  (indicated  by  a valid  Pointer  p)^ 

,2  sue  fP)  is  a successor  task;  hence  reducing  the  COUNT  for  this  task 
eonstittites  “erasing**  the  edge,  because 

,3  when  all  edges  into  a task  have  been  erased^  its  ggunt  will  he  zero^  so 

,4  insert  this  task  into  the  Tsort  list,  and  adjust  the  Tail  t accordingly, 

.3  Follow  the  successor  list  to  the  NEXT  item,  and  repeat  (as  long  as 
there  are  valid  successors)* 


I 

I 

S 

1 

I 

! 
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Chart  Number  1.5.7 

Module  Name  DIAGMOSE 

Date  4/12/77 

&t1.5.7)  DIAGNOSE  the  WBS  network 

The  module  described  here  is  at  present  a STUB. 

On  entry,  only  T < ntasks  have  been  entered  into  the  TSOftT  list.  Those 
tasks  not  listed  in  TSORT  have  non^zero  GOUNt  entries. 

This  procedure  currently  only  emits  a diagnostic  message  and 
nbtificatton  that  this  feature  is  not  yet  implemented. 

On  exit.  then,  there  is  no  change  in  the  data  space. 

On  coinpietibh,  this  module  will  piiiht  the  task  codes  for  all  tasks  having 
a non-zero  COUNT.  Not  all  of  these  are  necessarily  iii  a loop^  but  there  is  at 
least  one  loop  among  diem.  This  module  will  then  print  "ONE  such  loop 
is”,  followed  b)  the  task  codes  of  a circular  path  in  the  WBS*  as 
determined  by  the  algorithm  on  page  543  of  Knuth  ('Reference  7.2,9)^ 

Batibnale:  The  features  of  this  stub  represent  user  enhancements  iii  the 
form  of  exception  handling;  The  mainline  program  features  can  be  checked 
using  a stub  at  this  point 
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5.(1. 7)  Compute  schedule  DATES 


Chart  Number  1,7 

Module  Name  DATES 

Date  4/14/77 


On  entry,  the  schedule  network  has  been  built  (gount  is  no  longer  used). 
The  topblbgical  sort  of  tasks  is  in  TSORT,  with  beginning  task  as  task 
TSORT(i),  and  coinpletion  as  TSORT(isrrASkS),  The  starting  task  date  (day  of 
year)  is  contained  in  the  DURatibn  field.  All  start,  finish,  and  float  times  are 
zero. 


This  procedure  scans  tsort  in  the  forward  direction  to  compute  early 
start  and  finish  times;  then  iii  reverse,  to  compute  late  start  and  finish 
times,  plus  the  float. 


On  exit,  the  task  attributes  EST,  EFIN,  L$T,  ufin^  and  float  have  been 
computed^  and  dur  of  the  starting  milestone  has  been  corrected  (to  zero)^ 


START. 


,1  Set  START  to  the  start  milestone  Dl/Ratibn  and  zero  this  DUR,  Then 
compute  EST  and  EFIN  for  att  tasks. 

.2  Now  equate  the  Latest  STart  and  Latest  MNish.  times  to  the 
Earliest  STart  time  (equal  also  to  the  earliest  finish  time)  of  the 
completion  milestone.  This  is  necessary  for  the  reverse  scan  in  the 
next  step. 

Finally,  compute  the  lst,  lfin,  and  float  times  for  all  tasks. 


.3 
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Chart  Number  1,7,1 

Miodule  Name  early-DATES 

Pate  4/14/77 

S.(1.7.1)  Compute  EARLY  start  and  finish  DAIES 

On  entry,  the  state  is  ideritical  with  DAirES/i.7»  the  network  is  built; 
T$OR^  contains  the  topologically  sorted  list,  and  all  schedule  dates  are 
missing.  The  DUR  attribute  of  the  start  milestone  contains  the  starting  date 
(day  of  year). 

This  procedure  computes  the  early  dates  and  corrects  the  OUR  of  the  start 
milestone. 

On  exit,  the  pURation  of  the  start  milestone  is  zero,  and  EST  and  EFIN  for 
each  task  have  been  computed,  start  contains  the  start  milestone  day  of 
year. 

4 Transfer  the  start  date  to  start  and  correct  the  oURation^  The 
procedure  uses  t to  index  through  Tasks  in  the  TSGRT  list  in  forwa:i:d 
order.  Begin  the  iteration  at  T=i, 

,2  and  continue  through  t~ntasks  (the  number  of  tasks), 

.3  For  the  current  TASK,  Point  to  the  successor  list,  and  fill  in  the 
Earliest  FINish  time.  The  Earliest  STart  time  for  this  task  will  have 
already  been  computed^  either  by  initialization  (starting  task)  or  by 
step  4,  below, 

*4  For  each  of  the  successors  of  the  current  TASK,  record  its  earliest 
start  time  as  the  early  finish  time  of  the  current  task  when  less  than 
that  previously  recorded. 

Then  advance  t to  pick  up  the  next  task  in  the  TSOrt  list,  and 
repeat  until  alt  tasks  have  been  processed. 


.5 


454  Appendix  L 


Chart  Number  UAA 

Module  Name  sucgessoim^ates 

Date  4/15/77 

S.(1«7.14)  Record  SUCCESSOR  early  start  DAISES  for  current  task 

On  entry,  P points  to  the  TOP  of  the  current  TASK^  and  the  EFIM  of  this 
task  has  been  computed 

This  procedure  sequences  through  the  successor  list  (if  any)  of  the 
current  TASK,  and  enters  EFIN  as  the  earliest  start  (est)  of  successor  tasks 
whenever  this  EFIN  is  larger  than  the  EST  of  that  successor  node. 

On  exitv  all  successors  of  the  current  TASK  have  been  notiiied  of  the 
schedule  constraiiits  placed  by  that  TASK. 

.1  Begin  a loop  to  sequence  through  the  successor  list.  During  this 
iteration 

,2  let  F be  a successor  of  the  current  task. 

.3  The  Earliest  STait  time  of  the  successor  must  not  precede  the 
f^arliest  F/Msh  of  this  TASK,  so  if  such  a requirement  had  previously 
been  entered  (‘it  was  initially  zero), 

,4  update  the  successor  Earliest  SJUrt  appropriately, 

,5  Advance  to  the  next  successor  in  the  list,  if  any,  and  repeat  until 
the  list  of  successors  is  exhausted^ 
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Chart  Nuinher  1.7.3 

Module  Name  lai^E-J\nd-FLOAT 

Date  4/14/77 

5i<1.7.3)  Compute  LATE  AND  FLOAT  dates 

On  entiy,  the  early  start  and  finish  times  for  eat^h  task  have  been 

Gomputed,  and  the  starting  milestone  ounation  reset  to  zero.  TSORT  contains 

the  topologically  sorted  list  of  NTASKS  items. 

This  procedure  scans  the  TSGRT  list  in  reverse  to  compute  late  start/ 

finish  dates  and  the  float  time. 

On  exit,  these  quantities  have  been  deposited  in  LST,  LFIN^  and  FLOATf. 

.1  Set  T to  locate  the  nexNto-last  item  in  the  TSCRT  list  (whose 
successor  list  must  be  the  project  completion). 

.2  Initiate  an  iteration  backward  through  the  tsqrt  list  (indexed  by  r\ 
and  continue  until  the  list  has  been  processed. 

.3  Pick  up  the  current  TASK,  preset  its  Latest  FlNisih  to  machine 
infinity,  and  point  to  the  lisl:  of  successors.  Since  LFIM  for  this  TASK  is 
to  take  the  minimum  value  of  the  latest  start  time  of  its  successors, 
the  initial  value  of  infinity  is  needed^ 

.4  Iterate  through  the  list  of  successors  of  this  TASK  (if  any)  and  record 
the  LFIN  of  this  task  as  the  LST  of  the  successor  task  when  this  LST  is 
smaller  than  the  lfin  so  far  recorded. 

.5  After  lfin  has  been  found,  compute  the  Latest  STart  by 
subtracting  the  ouRation^  and  compute  the  float  as  .shown.  Finally, 
decrement  T to  pick  up  the  next  element  in  TSQRT,  and  repeat  until 
TSQRT  has  been  coinpletely  process^. 
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Chart  Nuiriber  lv7.3,4 

Module  Name  task-late-.date 

Date  4/15/77 

541.7.3.4)  (tecord  curreiit  TASK  LAT£  starting  DATE  from 
successors 

On  entry,  p pomts  to  the  list  of  sUGeessor  packets  of  the  current  TASK. 
LFIN  of  the  current  task  has  been  iniiiali^jd  to  infinity.  The  LST  values  of 
all  successor  nodes  have  already  been  computed  due  to  the  in-proeess 
reverse  scan  through  the  TSORT  list; 

This  procedure  sequences  through  the  successor  list  (if  any)  of  the 
eurrcnit  task,  and  sets  the  LFIN  of  this  task  to  the  LST  of  successor  tasks 
whenever  that  LST  is  smaller  than  the  current  LFIN. 


On  exit,  the  LFIN  for  the  current  tiisk  has  been  established^ 

. 1 Prepare  to  iterate  through  the  list  of  successors. 

.2  Pick  up  a suGcessor  task  F. 

.3  The  latest  F/jYish  time  for  the  current  TASK  must  not  exceed  the 
Latest  STart  of  a suGcessor;  hence,  if  it  does, 

.4  correet  that  situation  as  shown. 

.5  Then  pick  up  the  index  of  the  next  successor  and  repeat  until  the 
successor  list  is  exhausted 
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Chart  Number  1.8 

Module  Name  display 

Date  4/14/77 


a(1b8)  DISPLAY  schedule  report 

On  entry,  TSQRT  contains  a list  of  tasks  in  topologically  sorted  order,  and 
the  task  early/late  start/finish  times  have  been  c^mputi^.  START  contains 
the  day  of  year  of  the  start  milestone,  header  contains  the  top-of-page  text 
to  be  used. 

This  procedure  prints  the  schedule  spectfied  in  fpnnat  7.5. 

On  exit,  the  entire  data  space  is  no  longer  required. 

.1  Read  in  the  calendar  data  base  so  that  the  START  date  appears  as 
CALDRiOj  and  GALDR(n)  contains  the  date  of  the  nth  workday 
following  START.  If  the  project  finish  goes  beyond  the  calendar  or 
beyond  maxdate  elements,  print  an  error  message,  but  do  not  abort;  in 
the  former  case,  insert  a ' 'DAV  n"  designator  into  GALDR; 

.2  lines  will  count  the  number  of  tasks  output  on  a page^  and  T will 
index  through  the  TSORt  list  Preset  these  for  later  steps. 

.3  For  each  of  the  tasks  1,. . .^ntasks, 

.4  test  whether  the  end-of-^page  is  near.  If  so,  advance  to  the  top  of  the 
next  page.  If  a tbp-of-form  character  is  available,  that  can  be  used;  if 
not,  print  line  feeds  to  space  correctly.  Indicate  that  no  tasks  have  yet 
been  printed  on  this  new  page,  advance  the  page  count,  and  print  the 
header  at  the  top  of  the  new  page,  using  the  data  prepared  in 
HEADEEU3ATA7i.l.3. 

.5  Print  the  task  code,  title,  DURation,  EST,  EFIN,  lst,  lfin,  and  the 
corresponding  dates  via  the  caldr  array.  Print  the  float  time.  If  dates 
exceed  the  calendar,  or  if  the  project  exceeds  MAXDATE  in  duration, 
print  ‘*day  n\  Print  iii  column  1 if  the  float  of  this  task  is  zero. 
See  7.5  for  format  details. 

,6  Then  indicate  that  a line  on  the  report  has  been  used,  advance  T 
forward  iii  the  tSORT  list,  and  repeat  until  the  tasks  have  all  been 


.7  Print  the  final  Gosmetic  lines  across  the  repc  i and  terminate. 

Note:  Some  implementations  of  this  proGedure  may  elect  to  sort  the  TSORT 
list  on  CODE,  TITLE,  EST,  LST,  EFiN,  or  LFIN  as  a Step  0 prior  to  the 
procedure  as  given  above.  A suitable  algorithm  is  given  as  Example  t.3.3,1 
in  Chapter  7 of  Reference  7.2.10,  but  the  definition  of  “elements  out  of 
order**  must  be  reversed. 
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Chart  Number  1:8,1 

Module  Name  CALENDAR 

Date  4/15/77 


5.(1.8.1)  Read  in  CALENDAR  file 

On  entry,  START  cdtitaihs  the  integer  dayrOf-year  on  whiGh.  the  project 
starts.  The  calendar  file  contains  a set  of  records  beginning  with  the  eiurent 
year.  The  nth  record  Gorrespotids  to  the  nth  day  of  the  year,  and  contains 
two  fields:  The  first  is  a boolean  value  (true  if  that  day  is  a workday,  false 
otherwise),  and  the  second  is  a string  denoting  the  date. 

This  procedure  fills  galdr  with  lFINi(NTASKS)  dates  having  a true 
workday  flag.  If  the  calendar  file  is  too  short,  fill  with  “day  where  m is 
the  project  day,  and  print  an  error  message.  If  the  project  goes  beyond 
MAXOATE,  also  signal  an  error. 

On  exit,  galdr  has  been  prepared,  and*  possibly,  error  messages  have 
been  emitted 

,1  Set  the  integer  variable  NDAYS  to  the  Number  of  project  DAYS 
required^  i.e.,  LFiN{!NTASKS),  or  to  MAXOATE,  whichever  is  smaller.  If 
LFINi(ifMTASKS)  > MANDATE,  priht  the  message  ■ 'PROJEGT  too  long”, 

.2  Advance  the  calendar  file  and  read  the  START-date  record.  Set  the 
ENDFILE  flag  false  if  this  can  be  done;  otherwise  set  ENDFILE  true  and 
print  the  error  message  “CALENDAR  too  shobt”. 

.3  Set  up  to  read  the  calendar  file,  starting  at  day  zero^ 

,4  and  iterate  through  ndays. 

,5-,  6 The  project  day  numiber  converted  to  a STRing  becomes  the  galdr 

enitiy  after  the  endfile  condition  occurs. 

,7-.  8 The  datefield  string  road  in  from  the  Galcndar  file  becomes  the 
GAL43R  entry  if  the  day  has  a true  workday  flag, 

.9  If  not  a workday,  decrement  the  day  count  to  counterbalanGe  the 
later  incrementation  in  step  11,  so  as  not  to  advance  the  project  day 
count. 

.10  Read  the  next  calendar  file  record^  print  the  error  message 

“CALENDAR  TOG  SHORT"  and  set  ENDFILE  true  if  reading  hits  an  endfile 
condition  on  the  attempted  read. 

.11  Advance  the  day  count,  and  iterate  until  caldr  contains  the 

required  number  of  daySi 
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Chart  Number  El 
Module  Name  error 
Date  4/18/77 


5^{E1)  ERROR  handling  raufhie 

On  entry,  some  error  condition  has  faemi  detected,  and  a message  has 
been  passed  to  this  routine  as  the  sole  parameter.  The  parameter  is  herein 
treated  as  a stnng;  however,  the  parameter  may  be  coded  as  the  integer 
index  into  an  error  message  array,  if  all  calls  are  properly  ^notated. 

This  routine  prints  “♦♦•♦ERROR****”  followed  by  carriage  return^  line 
feedj  and  the  parameter  m^age. 


On  return^  there  has  been  no  change  in  the  program  data  space  state. 
No  flowchart  pf  this  procedure  is  given. 

Called  from! 

1.2.6, 6.7 

1.2.8.3.3 

1.2.8.6.4 

1. 5.7.1 

L8.1.1  (implicit) 

1.8.1.2  (implicit) 

115.1.10  (implicit) 

51.10 
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Chart  Muitiber  FI 

Module  Name  STR 

Date  4/18/77 

&(H)  StFtIng  functidn 

This  function  converts  its  integer  argument  value  to  a string  value.  The 
rehirned  string  is  the  character  representation  of  the  integer,  left  and  right 
justitied  (le.,  no  spaces).  No  decimal  or  commas  appear  in  the  format  If 
the  input  value  is  positive,  the  output  strii^g  is  unsigned;  if  negative,  the 
output  is  preceded  by  a minus  sign. 

No  flowchart  of  this  procedure  is  given* 

Called  fromt 

1.8.1.6 
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Chart  Niiinber  SI 
Module  Name  search 

Date  4/M/77 


S.(S1)  SEARCH  for  task  given  task  code 

Oh  ehti^,  two  arguments  have  appeared.  The  first  is  the  task  code  TCOpE, 
and  the  other  is  the  corresponding  task  number  TSK  to  be  returned  The 
current  nuniber  of  tasks  is  ntasks»  and  this  number  of  task  codes  appears  in 
the  schedule  network.  The  overflow  flag  OVRLOW  is  false;  all  data  except  the 
parameters  are  global 

This  routine  searches  through  the  task  codes  already  entered.  If  TCOPH  is 
founds  the  corresponding  number  is  set  into  TSK.  If  not  found,  but  room 
exists,  then  NTASKS  is  advanced  one,  and  tgODE  is  made  the  task  code  of  a 
new  network  node.  If  not  found  and  there  is  no  room,  the  OVFLOVy  flag  is  set 
truet  MORE  is  set  false,  and  the  diagnostic  message,  “I^ask  overflow’'  is 
prints. 

On  return,  either  TSK  has  been  set  to  the  asked-for  task  nuniber  and 
OVFLOW  is  false,  or  else  ovflow  has  been  set  true,  in  which  cose  TSK  is  not 
meaningful  more  wilt  have  been  set  false  on  overflow. 


Stiib  rationale:  Although  slow  and  probably  unsuitable  for  full 
operational  use,  the  linear  search /insert  procedure  is  sufficient  for  checking 
the  algorithms  in  the  remainder  of  the  program.  On  cohipletibh^  this 
routine  may  well  take  the  form  of  a hash  table  lookup  of  tCODE  in  the  eoDE 
array,  as  the  program  is  not  sensitive  to  the  order  in  which  tasks  appear  in 
the  network. 

. 1 Initialize  TSK  and  Nt  for  searching  the  CODE  array. 

.2  and  search  until  the  task  is  found  or  until  all  current  codes  have  been 
examined. 

.3%4  When  the  CODE  at  TSk  agrees  with  that  sought,  stop  the  search. 

.5  Otherwise,  increment  the  TSK  index  to  continue  searching. 

.6  NT  will  be  zero  or  larger  if  no  match  was  found. 

.7  Thus,  if  there  is  rooni  to  insert  a new  task  code, 

.8  increment  ntasks  (tsk  is  NiTASKS+i  by  now),  and  enter  TGObE  into 
CODE  at  that  point. 

.9  If  there  is  no  room  for  another  task  code,  signal  overflow  and  no 
more  action  required, 

.10  and  print  an  error  message. 
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S.2  Data  Structure  Definitions 

Data  structures  defined  in  this  specification  are  consider^  by  this  design 
to  be  globally  accessible,  so  as  to  promote  codability  in  almost  miy  host 
language.  Coding  in  languages  that  permit  localized  scoping  and:  limited 
accessibility  to  diita  iiiay  arrange  such  declarations  so  as  to  contribute  to 
more  reliable  programming  practice. 

Variables  and  constants  used  in  this  program  are  defined  in  the  glossaty 
(7.1).  Amalgamation  of  arrays  to  form  the  schedule  network  is  discussed  in 
Section  5<0. 


6.  TEST  AND  VERIFICATION  SPECIFICATIONS 


s 


6.1  Production  Testihg 

During  the  coding  activity  that  impleinents  this  program,  iiiput  data  shall 
I be  used  to  drive  the  program  through  eveiy  *‘flow  line**  of  the  procedures 

i at  least  pnce^  WBS  networks  shall  be  input  to  (singly)  violate  each  of  the 

I network  boundary  conditions.  Siich  data  shall  include; 

! a.  Empty  WBS. 

b,  WBS  consisting  only  of  “END"  record.  ‘ 

e.  WBS  not  ending  with  “end"  record, 
d More  than  maxtASKS  tasks  in  the  WBS. 

e.  More  than  M/ocsyc  linkages  (predecessors)  in  the  WBS^ 

f.  Tasks  with  no  predecessors. 

g.  Tasks  with  no  successors. 

h.  FINi$M  task  with  suGcessors. 


I 

I 


i.  WBS  has  a circular  set  of  tasks. 

j.  WBS  of  moderate  size  (more  than  one  output  page)  formatted 
correctly  and  within  boundary  constraints^ 

Acceptance  Test  Specifications 

The  program  described  herein  shall  be  deemed  suitable  for  operations, 
provided  acceptance  tests  demonstrate; 

a.  Proper  response  to  the  tests  in  Section  6- 1. 

b.  Error^ree  performance  on  several  WBSs  ranging  in  size  over  the 
acceptable  limits. 
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e.  The  cltitcetion  of  all  of  nine  calibratiion  errors  of  a random  nature 
inserted  into  the  program  using  the  test  data  in  (a)  and  above*  in  a 
special  test  version  for  assessing  test  adequacy. 

&3  QuaOty  Assurance  Measures 

Quality  Assurance  personnel  shall  audit  the  code  resulting  from  this 
specification  and  attest  that  such  code  is  a faithful  translation  of  the 
documoUed  procedures*  that  programming  standards  hiive  been  adhered  to* 
and  that  all  inachine-depemdent  eonsidcrations  conform  within  the  limits 
specified  herein.  Such  personnel  shall  then  conduct  or  elosel)'  monitor  the 
acGcptancc  tests  specified  in  Section  6.2,  above, 

7.  APPENDICES 

7.1  Gtbdsary 

This  appendix  contains  the  names  of  program  modiiles*  variables, 
constants,  textual  acronyms*  and  special  terms  used  in  this  document 

AVAIL:  AVA/LiibIc  list  pointer.  A '^pointer”  into  sliiCrNEXT  arrays.  It 
contains  the  integer  index  of  next  avaihdde  pair  to  be  attached  to  the 
network.  Value  ^ maxsug. 

B:  bottom  of  unsorted  list  An  integer  index  into  the  tsort  array.  In 
REGISTER/ 1.2,6,  the  htsks  from  B to  maxtasks  are  um  orted. 

BUILD/1.2:  Procedure  name  of  the  module  that  builds  the  schedule 
network. 

CALDR:  CAAxjivDai?  array.  Array  0, , .maxdate  of  date,  where  date  is  cither 
a string  such  ;ts  1SAPR77  or  integer  such  as  1 50477,  which  converts  to  a 
date  in  the  form  15APR77  in  l.S.l.S. 

CALENDAR/1.S,1:  Procedure  name  of  module  that  reads  calendar  file  into 
GALDR  array. 

GIIECKJ5UCCESSORS/1, 2.8,3:  Procedure  name  of  module  that  prints  a 
list  of  task  codes  which  have  PINISH  as  a suceessor, 

CODE:  Task  CODE  array.  The  string  arra\\  ten  characters  by  MAXTASKS* 
indexed  by  task,  which  contains  ta.sk"Code  identifiers  suppliefl  to  each 
task  in  WBS.  Size  ^ maxtasks. 

GOiMNEGT/  L2i6i6;  Procedure  name  of  the  module  that  links  predecessor 
tasks  to  the  Gurrent  tnsk  in  the  schedule  network. 

COUNT:  The  integer  array  indexcXl  by  TASK  as  part  of  the  schedule 
network*  which  records  the  number  of  predecessors  for  the  given  task 
node.  Size  :<  maxtasks. 
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GP!Vf:  Critical  Ail:h  Method,  An  algorithm  for  locating  those  tasks  in  a 
schedule  whose  slippage  will  cause  the  project  termination  date  to  slip 
also. 

DATEFIELD:  String  variable  to  hold  the  calendar  file  work  date  read  into 
the  program. 

DATES/i.7:  Procedure  name  of  modliie  that  computes  late  and  early  start 
and  finish  dates,  and  the  float  times  for  the  schedule  network, 

DAY:  An  integer  index  denoting  the  project  day  beyond  START.  Day  0 is  the 

. project  start. 

D1AGNOSE/1.5J:  Procedure  name  of  module  to  diagnose  a schedule 
network  having  a loop. 

DlSPLAY/1.8:  Procedure  name  of  module  that  prints  the  schedule. 

DURt  DC/Ration;  The  integer  array,  indexed  by  TASK,  which  contains  the 
durations  of  the  referenced  tasks  in  the  schedule  network,  in  days.  Size  < 
M/^ASkS. 

EARLYJpATES/ 1,7.1:  Procedure  name  of  module  that  computes  early 
stait  and  finish  dates  for  the  schedule  network. 

EPIN  : Early  P/A^ish  time.  The  integer  array,  indexed  by  task  as  part  of  the 
schedule  network,  which  contains  the  earliest  finish  times  of  tasks, 
reckoned  in  days  from  start.  Size  ^ maxiasks. 

ENDFILE:  Boolean  flag  set  true  when  an  endfile  is  found  while  attempting 
to  read  calendar  file  record. 

ERASE.^i^GES/1.5k4:  Procedure  name  of  module  that  -"erases"  edges  to 
successor  nodes  by  reducing  the  count  field  of  those  nodes, 

ERROR/El::  Subroutine  that  prints  the  string  parameter  passed  to  it  as  an 
error  m^age. 

EST:  Early  STart  time.  The  integer  array,  indexed  by  task  as  part  of  the 
schedule  network,  which  records  the  earliest  start  tiitie  of  tasks,  reckoned 
in  days  from  start.  Size  < maxtaskS; 

F:  An  Integer  index  that  locates  the  Front  of  the  tsort  queue  in  topqsqrt/ 
1.5.  It  is  also  used  to  process  dates/L7. 

Float f The  difference  between  latest  and  earliest  start  of  a task  in  a 
schedule  network. 

FLOAT:  An  Integer  array  indexed  by  task  as  part  of  the  schedule  network, 
to  record  float  times^  in  days.  Size  MaxtaskS: 

HEADER:  String  information  necessaiy  lOr  schedule  header.  See  Section 
7.5  for  typical  format  of  output;  however.  Header  is  not  specified  in 
detail  in  this  document. 
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INi1ilALIZE/l  J:  The  procediire  name  of  the  module  that  declares  all  data 
stnicturcs  and  constants. 

LATHLANIO'LOAT/L?,^:  Procedure  name  of  module  that  computes  late 
start  and  finish  dates,  and  the  float  time  for  a schedule  network, 

LFINt  f.atest  F/jVish  time.  An  integer  array,  indexed  by  task  as  part  of 
scliedule  network,  which  records  latest  finisli  times  of  tasks,  reckoned  in 
days  past  start.  Size  < maxtasks, 

LIN'ES:  All  integer  variable  used  to  count  the  mnnhtr  of  lines  put  out  on 
the  current  page. 

LINKJFQJ^fNISH/ L2,S*6;  l"he  procedure  name  of  a module  that  links  a 
given  node  to  the  FiNiESH  node  if  it  hits  no  successors, 

LST:  Latest  STart  time.  An  integer  array,  indexed  by  TASK,  as  part  of  the 
schedule  network,  vvliich  f^cords  the  latest  start  times  of  tasks,  reckoned 
in  days  from  start.  Size  maxtasks. 

MAXDATE:  An  integer  program  parameter.  The  rniLvinnim  length  of  time 
that  can  be  scheduled  in  a project.  A compile-time  constant 

MAXSUC:  iWAA'iimim  nuinbef  of  S(/C:next  pairs  to  be  allowed  in  network. 
A compile-fciinc  integer  constant 

MAXTASKS:  A/AAiiiUiin  number  of  T/VSKS.  A coinjule-tinic  integer 
Gonstaiit 

Milestone:  An  achievement  .signalled  by  the  acconiplishment  of  a task  or 
set  of  tasks.  In  this  program^  a milestone  is  a zero-duration  task  linked  to 
predecessor  tasks  in  order  to  show  achievement  of  all  preceding  tasks 
before  advancing  to  a next  set  of  tasks. 

MORE:  A boolean  used  for  loop  control.  Set  false  by  seargh/SI  if  task 
overflow  occurs. 

MOREPRED:  A boolean  loop  flag,  true  while  iterating  upon  predecessors 
of  a node  in  register/ 1.2.6. 


NDAVS:  The  integer  A^umber  of  project  DA  TS,  total  diiration  or  limited  by  | 

MAXDATE  in  CALENBAR/ 1.8, 1. 

NEXT:  A ‘ pointer'*  array  indexed  liy  “pointers/*  An  element  contains  the 
Index  of  the  next  sog:  NEXT  pair  for  succes.sor  nodes  of  the  current  task  in 
the  schedule  network.  Size  :<  MAXSGG.  * 

NIL:  A compiler  constant  equal  to  zero,  to  represent  the  null  pointer.  The  ■ 

invalid  integer  hidex  into  SUG:NEXT  arniys  that  iiidicates  no  further  ^ 

successors  are  present. 

NONiNIL:  Any  non-tiil  value  of  “pointer**  into  SUC:  NEXT  arrays.  Used  in 
TERMiNATOR/1.2,8,  A eoinpile-time  coiistaiit.  I 
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NT:  An  integer  variable  locd  to  the  stub  SEARGH/SI,  used  to  eotltrol  the 
searcll  Initially  set  to  the  ATumber  of  Tasks,  but  reset  to  ^1  if  the  sought 
task  code  is  found, 

NTASKS:  An  integer^  the  current  A/uiriber  of  TASKS  input  into  the 
schedule  network.  Value  ^ MAKTASKS* 

OVFLOW:  A boolean  variable,  false  unless  task  or  successor  linkage 
overflows  occur. 

P:  Pointer.  A “pointer”  into  suG:NEXT  arrays,  used  in  various  localized 
procedures^ 

PAGE:  An  integer  value  used  by  DISPLAV/  I S to  record  the  page  number  of 
the  WBS  report. 

PEBT;  Program  Evaluation  and  lleview  Technique.  A method  that  aids  in 
the  plannings  scheduling,  monitoring,  utilization,  and  reporting  of  project 
resources  by  means  of  task  definition,  wbrk  breakdown  structures, 
resource  constraints,  and  schedule  networks. 

Pointer:  The  index  of  SUC:  NEXT  array  elements. 

FEED;  jRREpecessor  task  code.  A strings  wbieh  is  a task  code  read  in  from 
a WBS  records  Local  to  gonnegt/1.2^6;6. 

PTASK:  Predecessor  TASK.  An  integer,  the  index  of  a predecessor  task. 
Local  to  cdNNEeT/1.2;6^ft 

REGISTER/1.2^6;  Procedure  name  of  the  module  that  enters  tasks  into  the 
schedule  network. 

SCHEDlJLER/1:  The  name  of  the  main  program. 

SEARCH/Sl:  Subroutine  to  seardh  for  a given  task  code  and  return  the 
task  number;  it  inserts  the  task  code,  if  not  found,  into  the  network,  and 
sets  OVFLOW  as  appropriate. 

START:  An  integer  variable  that  contains  the  project*start-milestone  day- 
of-year  read-in. 

STR/¥h  The  Sl^ng  functioiL  which  converts  an  integer  variable  to  a 
string  variable.  Used  in  gal^dar/1.8A. 

SUG;  successor.  A “node"  array  indexed  by  "pointers"  to  denote  edges  in 
the  schedule  netwprkv  The  “node"  value  is  an  index  into  task  informaition 
arra^ys.  Size  ^ maxsUC. 

SUCGESSORJi)ATES/L7.1.4;  Procedure  name  of  a module  that  calculates 
the  EST  restrictions  placed  on  successors  of  the  current  task. 

T;  An  integer  index  of  the  tsort  list.  During  sorting,  the  tasks  in  tsgrt 
indexed  1,. . .,t  are  in  sort^  Tasks  beyond  are  probably  not.  T ^ ntasks. 
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Task:  An  item  In  a Work  Breakdown  Structure  (WBS)  characterized  by 
work  with  definable  inputs  and  outputs,  predecessor  and  successor  work 
constraints,  probable  or  estimated  duration,  and  assigned  responsibiUties, 

TASK:  An  integer  index  into  the  task  information  arrays  in  the  schedule 
network,  task  j<  ntasks. 

TASKJlATEJi>ATE/].7.3.4:  Procedure  name  of  a module  that  calculates 
the  CFIN  of  the  current  TASK  from  the  LST  of  all  its  successors. 

TASKCODE:  A string,  recording  the  task  code  input  in  81)11.0/1.2.  If  “ENO" 
appears  as  a task  code,  then  no  more  tasks  will  be  input 

TCODE:  A string  parameter  pas.sed  into  the  sbib  SEAflG)S/Sl  having  the 
value  of  the  sought-for  Task  CODE. 

TERM'INATOR/I.2.8:  Procedure  name  of  the  module  that  adds  the 
“finish”  milestone  to  the  schedule  network. 

TITLE:  A string  array.  32  characters  X maxtaskS,  indexed  by  task,  which 
contains  the  task  title,  as  part  of  the  schedule  network.  Size  & maxtasks. 

TOP:  A ‘‘pointer”  array  indexed  by  task  as  part  of  the  schedule  network, 
TOP  “points”  to  swcrNEXT  array  elements  to  give  .successor  information. 
Size  < MAXTASKS; 

TOPOSORT/1,5:  Procedure  name  of  module  to  sort  the  tsort  list 
topologically. 

TSORT:  Topological  SORT  list.  An  integer  array  indexed  by  t,  which 
contains  topologically  sorted  list.  The  first  element  is  the  task 
number  of  the  start  milestone.  While  being  constnicted,  item.s  up  to  T 
are  sorted.  Items  from  B to  MAXTASKS  are  tasks  held  for  later  query  by 
TERMINATOR/ 1.2.8.  Size  £ MAXTASKS. 

TSK:  An  integer  parameter  passed  from  stub  seahch/SI  having  the  Value  of 
the  TaSK  number  corresponding  to  an  input  task  code. 

WBS:  Work  Breakdown  Structure,  or  hierarchy  qf  tasks  refined  into 
subtasks  until  siibtasks  are  finite,  manageable  units, 

WORKDAY:  A boolean  variable  to  hold  the  calendar  file  workday  fiag, 
true  if  the  corresponding  day  is  a workday,  false  otherwise. 


7^2  References 

,1  Prather,  R.  E.,  Discrete  Mathematical  Structures  far  Computer  Science, 
liloughton  Miifiih  Company,  Boston,  MA,  pp,  220^-278,  lS76. 
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.2  Df)D  nnd  iVAS^V  GmiV/c*  PEHT/Cost  Systems  Dcsigp^  Office  of  the 
Secretary  of  Defense  and  the  National  Aeronautics  and  Space 
Adniinistration^  U,S.  Covemmcnt  Printing  Offiee,  Washington j DC, 
June  1962. 

A deseription  of  the  PERT  system  application. 

.3  Ap/j//crtf/nn  De,vtTipftort  \tanuah  1130  Project  Control  SystofUy  IBM 
Corp.,  White  Plains.  NY,  1968. 


IntrodiiCtory  guide  to  the  use  of  the  IBM  program,  with 
some  theory  and  examples* 

.4  Tauswdrthe,  Robert  C.,  Standardized  Development  of  Computer 
Software,  Part  If:  Standards,  Chapter  16,  this  text 

Defines  documentation  levels. 

*5  Chapter  12. 

Contains  documentation  standards  and  guidelines. 

.6  Ibid*,  Chapter  13* 


Contains  coding  standards  and  giiidetines. 

.7  Ibid.,  Chapter  14. 

Contains  testing  standards  and  guidelines. 

.8  ffoirf,.  Chapter  15. 

Contains  QA  standards  and  guidelines. 

.9  Kmith^  D.  E.,  The  Art  of  Computer  Programmings  Vol  h Femf/omentfi/ 
Algorithms,  Addison-Wesley  Publishing  Co.,  Reading,  MA,  pp*  262- 
265,1969. 

Gives  the  topological  sorting  algorithm  used  here* 

,i0  Tausworthe,  Robe**!  C*,  Standardized  Development  of  Computer 
Software^  Part  I:  Methods,  Prentice-Hall  Publishing  Company, 
Engl^oqd  Cliffs,  NJ,  1977. 


Gives  the  general  methodology  for  top-down,  modular, 
stniGtured  development  of  programs^ 
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7.3  Potential  Future  Modifications 

The  extension  of  the  program  specified  here  into  a fn!!  project  planning, 
evaluation,  and  reporting  tool  is  not  covered  by  this  specification; 
However,  several  candidate  features  are  deemed  nec:^ssary  in  such  a tool 
These  aret 

a.  Data-base  operation.  Including  update  Gapability, 

bi  Gapability  to  assign  resources  (manpower,  dollars)  and  to  allocate 
fuGilitics  to  individual  htsks, 

c.  Access  to  alternate  calendars. 

4 Capability  to  enter  required  or  actual  dates  for  milestones. 

e.  Options  to  print  other  t)^pes  of  reports,  such  as  schedule  (GANTT) 
chart,  milestone  data  only,  cmmilative  duration  rate  chart,  resource 
expenditure  profile,  sorted  soliedule  according  to  Gompletion  or  start 
date,  etc. 


7.4  Error  Messages  and  Diagnostics 

This  appendix  contains  a list  of  the  error  messages  and  conditions  under 
which  these  are  invoked,  as  specifietl  by  Sections  4 and  5 of  this  document, 
Otiier  error  messages  may  appear  ii  host-dependent  considerations  dictate. 

All  error  messages  output  by  euror/EI  wilt  appear  precede  by 

Ox^erflow  errors  terminate  processing,  whereupon  the  following  message 
appears  appended  to  the  prefix  above: 

SGHEDUUER  TERMINATED 

The  detected  errors  are  as  follows: 

CALENDAR  TOG  SHORT 

Calendar  file  does  not  cover  the  luiinber  of  days  in  the  project; 

task  code  CANNOT  FOLLOW  ^’FINISH" 

The  WBS  has  a finish  task  with  a successor  task  identified  by  task 
code. 

LINKAGE  OVERFLOW 

1'he  schedule  network  has  too  many  successor  relationships  (edges). 
TASK  OVERFLOW 

The  WBS  has  too  niiuiy  tasks  (nodes). 
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WBS  HAS  AT  LEAST  ONE  GN'GLE  AMONG  TASKS 

The  schedule  ne^ork  contains  a circular  set  of  predecessor- 
successor  relationships. 

7.5  Output  Report  Fermat 

The  output  report  format  is  defined  in  Figitre  7.3.1.  The  top  line,  giving 
the  project  name,  is  the  header  record  input  by  HEADER-DATA/ 1,1.3.  The 
report  date  is  assumed  available  via  the  operating  system.  The  format 
displays  the  variou.s  field  widths,  and  gives  a Epical  example.  Asterisks 
signal  critical-path  items. 

END  OF  SPECIFICATION 
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EXAMPLE  L-2 

DECISION  TABLE  CONVERSION 
USING  THE  POLLACK  PROCEDURE 


1.  INTRODUGTION 
U 1 ggrpose 

7his  program  converts  a limited  ent^  decision  table  (liEDT) 
input  by  a user  to  a GRiSP  program  using  the  PoiiacK 
'^pptimiratloii“  procedure,  based  on  a least- dec  is  ion- time  cost 
criterion* 


This  specification  covers  only  machine-independent 
considerations  relative  to  ii^len^ntation*  standards  and 
Conventions,  CyStem  environment  and  interfaces,  test  and 
verification  details,  and  other  lower-level  considerations  are 
not  covered* 

1. 3 Apolicable  Document 

Robert  G*  Tauswbrthe,  standardised  Development  of  Computer 
software*  Part  r*  standards*  Chapter  a#  section  8. 3 . 3 through 
8.3.5,  pages  250!^271>  Prentice-Hi^l,  Englewood  Gliffs;,  N-J.,  19 7' 
(Reference  5. IJ • 

1.4  General  Description 

The  application  of  IEDTr*s  to  generation  Of  flowcharts,  and 
therefore  GrIsp  programs,  is  covered  by  the  applicable  document 
named  above,  the  Pollack  procedure  herein  described  is  a 
recursive  algorithm  for  procesCihg  an  ^ b composed  of  condition 

stubs  and  entries,  action  stubs  and  entries,  costs  associated 
with  each  condition,  and  probabilities  associated  with  each  rule. 
No  ‘♦don*t*care«  entries  are  ^rinitted  in  the  LEDt  Input.  The 
basic  procedure,  due  to  i^llack  (Reference  5,2),  converts  an 
unambiguous  bEDT  into  a flowchart  (or  CRiSF  program)  as  follows: 

a*  Select  one  row  of  the  drigihal  tEOT  by  a suitable 

Criterion  G (to  be  disbussed  later) , The  condition  in 
that  row  becomes  the  first  comparison  of  the  flowchart. 


* 
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b*  Decompose  the  table  into  two  subtables  having  one  less 
row  * either  subtable  may  ^rhaps  only  contain  one 
action  - and  associate  each  subtable  with  a branch  of 
the  flowchart  decision.  That  is,  one  subtabie  consists 
of  ail  the  remaining  conditions  and  the  set  of  rules 
for  which  the  condition  selected  In  (a)  above  is  true; 
the  other  is  similar,  except  that  the  cemdition  is 
false, 

c*  If  a subtabie  has  tore  than  one  action,  select  one  of 
its  rows  by  criterion  C and  attach  the  condition  for 
that  row  to  the  proper  branch  of  the  previbusiy 
selected  condition  producing  that  subtable. 

d.  Gontinue  (b)  and  (c)  above  on  each  subtable  until  each 
rule  of  the  original  lEDT  is  represented  in  a branch 
of  a condition  for  until  a subtabie  indicates  that  the 
original  table  contained  redundant  or  contradietojy 
ruies) * 


The  criterion  C,  above,  can,  among  other  things,  check  for 
redundancy  or  contradiction  among  rules,  if,  at  any  stage,  two 
rule  columns  exist  without  containing  at  least  one  pair  in 
some  row,  redundant  or  contradiction  exists.  If  the  actions  for 
both  rules  are  the  same,  the  rules  are  redundant  and  qne  can  be 
eliminated;  if  the  actions  are  different,  the  rules  are 
contradictory,  and  the  table  is  in  error* 

The  criterion  C applied  in  this  program  (denoted  as 
criterion  G1  in  the  document  referenced  in  section  1.3  above) 
computes,  for  each  cohditlon  to  be  tested  in  a given  (sub)  table., 
the  decision- time^cost  for  that  declsioh  multiplied  by  the  sum  of 
probabilities  of  ail  rules  r t and  r^  in  the  (sub)  table  such  that 
xTi  < r^,  tdiose  action  entries  are  the  same,  and  whose  condition 
entries  permit  a *»don'»t  care"  condition  to  replace  a V-N  pair. 
This  value  for  a given  condition  is  Icnown  to  be  the  expected 
extra  time  contributed  to  the  execution  of  a program  if  that 
condition  becomes  the  one  selected  in  step  (a)  above*  The 
criterion  C used  here  chooses  the  condition  so  as  to  minimise 
this  ei^ected  extra  time* 

The  reader  is  referr^  to  the  cited  applicable  document  for 
further  informatioh  tegarding  the  general  method. 


2,  THE  METHOD 


The  condition  stub  in  an  LEDT  may  be  eliminated  from 
processing  if  each  of  the  condition  entry  Y*s  and  M‘»  s can  be 
tagged  with  the  number  of  the  condition  to  which  it  applies. 
Thus,  a Y2  in  the  table  would  make  it  clear  that  a Y response  to 
conditipn  2 applied  at  that  poi^^*  program  d^cribed  in 

Action  5 uses  ti  and  “1  to  record  Y and  N answers  to  condition 
i,  respectively,  such  tagging  is  neceseai^  in  Oider  to 
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interch^ge  condition  rows  and  rearrange  rule  columns  in 
subtabies  of  the  LEDT. 

Starting  with  the  complete  table^  let  the  best  condition  be 
found  according  to  the  eriterian  C abdve,  suppose  this  were 
condition  3.  Then  interchanging  condition  rows  3 and  1 brings 
the  best  condition  to  the  top  of  the  table.  m%t,  by  exchanging 
columns  of  the  tEEMP  appropriately*  all  columns  with  V responses 
to  the  top  condltton  can  be  made  to  appear  to  the  left  of  ail 
columns  with  in  the  top  row.  The  subtable  with  a y answer  to 
the  top  condition  extends  from  column  I on  the  left  to  the  middle 
of  the  table  on  the  right*  and  from  oondltlon  row  2 on  down.  The 
same  procedure  may  now  be  applied  to  each  of  the  two  subtables 
just  formed. 

In  general,  then*  the  method  is  the  recursive  application, 
starting  at  a TOP«1,  LEFT*1*  and  RlGHt*2*»n*  of  the  following 
steps:  <1)  for  each  subtable*  determine  the  best  condition  row 

between  TOP  and  n*  based  oh  the  rules  from  LEFT  to  RtGBT* 
exchange  this  condition  row  with  the  TOP  row  between  lEFt  and 
RX6ST  limits,  (3)  permute  columns  to  arrange  ail  Y answers  on  the 
TOP  row  to  be  left  of  all  K answers*  f4)  determine  the  Mlb  column 
as  the  first  E response  in  the  TOP  row*  and*  filially*  (5) 
initiate  the  optimiration  of  two  subtables  with  a new  TOP  of 
TOP^i,  and  boundaries  <LEPT,  MID-t)  and  (MID,  RIGHT) , 
respactively.  that  permuting  columns  of  a subtable  never 

Changes  the  condition  entries  above  TOP. 


Each  time  a best  condition  is  found,  it  la  printed  in  ah  IF 
statement;  the  value  of  TOP  indicates  the  level  of  nesting,  and, 
thus*  the  indentation  to  be  used^  The  left  subtable  corresponds 
to  the  THEH  clause*  and  the  right  subtable  to  the  EbSE  clause. 
Hence*  upon  rOturning  from  prodessing  the  left  table*  an  (BtSH) 
is  printed.  After  pfocessing  the  right  subtable,  ah  EMbiF 
completes  the  processing  of  that  subtable. 

Whenever  a subtable  possesses  rules  that  all  invoke  the  same 
action*  then  no  condition  needs  to  be  tested;  hence*  a text  which 
indicates  the  action  is  printed  at  that  point*  and  no  further 
processing  of  the  subtable  takes  place. 


3i  PONGTIGNAl  SPECIFICATIONS 

This  program  as  specified  here  accepts  an  t»£tiT  from  an 
unspecified  medium  in  an  unspecified  format;  however*  the 
infortnatipn  input  shall  be  eguivaleht  to  that  shown  in  Pipure 
8-ip  of  the  cited  applicable  document.  These  entries  include  the 
followings 


3 


Example  Lr2  481 


a.  Number  at  eondltione;  an  integer*  n in  Section  2* 
above* 

b*  Condition  text:  strings  which  state  the  conditions 

appearing  jSTthe  conation  stub*  one  string  per 
condition.  These  will  appear  in  IF  statements. 

c.  Action  text:  strings  which  identify  action  sets 

invoked  by  rules.  These  will  appear  in  THEN  and  ELSE 
clauses. 

d.  An  action  assignment  list,  which  matches  indices  of 
action  texts  to  their  proper  rules*  listed  in  a 
standard  order. 

e.  A probability  list.  Which  matches  execution  frequencies 
to  their  proper  rules*  listed  in  the  same  standard 
order  of  rules. 

f . Condition  test  times,  which  state  the  times  required  to 
test  each  of  the  given  conditions. 

Processing  this  input  as  described  in  the  citBd  document 
produces  ah  indented  GKISP  listing  of  the  program  consisting  of 
nested  IFTHBNEXSE  structures.  The  condition  text  strings  are 
placed  in  IF  statements,  when  a rule  is  finally  resolved  by 
nested  condition  outoomes*  the  clause  corresponding  to  that  rule 
is  the  action  iext  htrihg  given  on  input  for  that  rule. 

The  following  example  serves  to  Illustrate  the  application 
of  this  program  and  specify  the  output  format.  The  example  shown 
in  Figure  8-10  of  the  cited  document  has 

a.  The  number  of  cohditions  (integer)  : 3 

b*  Condition  text  (strings)  ; G1*  G2*  G3 

c«  Action  text  (strings):  A1*  A2*  A3 

d.  Assignment  list  (integers! ; 1*  1*  3*  2*  1*  2,  2,  2 

Probability  list  (reals) ; .1*  .15,  .15*  .2*  .25,  .05, 

.05,  .05 

Condition  test  times  (reals):  50.>  68^,  25. 

In  (01  and  (d)  note  that  the  action  assignments  and  probabilities 
are  not  given  in  the  same  order  of  rules  as  shown  in  the 
referenced  figure.  So  as  to  avoid  having  to  input  individual  Y-N 
entries  into  the  condition  stub*  thie  program  assumes  a standard 
cgnditioh  stub*  ranging  from  all-Y  as  rule  i*  to  ail-rN  as  rule 

progressing  in  binary  radix  form  With  the  bottom  condition 
toggllhg  every  title*  etc. 
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Thfi  output  for  this  example,  corresponding  to  Figure  6- It  in 
the  reference,  is 

IF  (C2) 

I IP  fC3) 

: : A1 

: :->(Etsfi) 

: : IF  (Cl) 

s : : At 

: ; ;->(ELSE) 

: : : A2 

: : I • . ENDIF 

: .ENDIF 

:-><ELSE) 

: IF  (G3) 

j : IF  (G1) 

: ; : A3 

; : :->(ELSE) 

: : : A2 

; : : . . ENDIF 

: :->(ElsE) 

: : A2 

: : , . ENDIF 

ENDIF 


4.  PROGRAMMING  SPECIFICATIONS 
4.0  Gverview 

The  major  data  structures  required  by  the  program  are  those 
required  to  form  the  elements  of  the  decision  table.  In  the 
specifications  below,  these  table  structures  will  be  considered 
as  global  to  all  modules  within  the  program,  but  only  for 
convenience  in  describing  the  algorithms.  Data  declarations  are 
not  covered  by  the  program  descriptions,  but  are,  of  course, 
necessary  once  the  programming  language  is  chosen. 

Subroutine  and  function  argument  parameters  are  assumed  here 
to  be  local  to  a subroutine  and  available  as  global  within  that 
subroutine  (i*e. , available  to  subprograms).  Thus,  a parameter, 
say  TOP,  passed  as  an  argument  to  the  POLLACK  subroutine  at  the 
main  program  level,  is  not  the  s^e  location  as  the  argument 
parameter,  TOP,  local  to  that  subroutine  and  accessed  by  , 
subprograms  PRINT_Else  and  PRINT^ENOIF.  Local  variables  are 
identified  in  the  narrative  discussions  of  each  program  module. 


Input  of  the  LEDT  is  handled  by  a subprogram  ENTER_LEOT, 
which  accepts  information,  as  described  in  Section  3,  above,  from 
an  arbitrary  medium  and  formats  it  for  the  recursive  subroutine 
POLLACK,  which  optimizes  the  table  and  prints  the  cosmetized 
translation  into  GRISP* 
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The  giotoal  data  structucee  are 


N Integer  number  of  conditions  in  the  I.BDT* 

CONDITION  String  array  holding  condition  stub  textual 
descriptionst  in  order 


PROB  Heal  array  holding  rule  probabilities,  for  rules 

in  standard  order 


A 

AGTIQM 

ROLE 

LBDT 


TIHEGQST 


Integer  nurnber  of  distinct  action  combinations. 

string  array  holding  textual  descriptions  of  the 
action  combihatioiis  which  apply  to  the  various 
rules, 

Integer  array  holding  indices  of  the  action 
strings  which  apply  to  each  of  the  various 
rules#  r=t . ,2**N,  in  standard  order* 

Integer  array,  N x 2**N  holding  the  Y-N  (or  T-P) 
condition  entries.  The  i,  j ^ element  is  ±c, 
where  corresponds  to  a true  outcou^  of 
condition  c,  and  -c  corresponds  to  the  false 
outcome.  Initially,  liEdTXi,  j)  = ±1;  i.e^,  the 
ith  row  records  the  Y-N  entries  foir  the 
condition,  for  each  rule  j Since 

subtabies  are  permuted  by  the  program,  the 
condition  correspondences  are  traceable  by  the 
entry  values- 

Real  array  of  times  required  for  maHing 
decisions,  for  each  condition 


Subtables  of  LEDT  required  by  the  pOllACK  subroutine  are 
defined  by  local  parameters  TOP,  LEFT,  and  RIGHT. 


I 

I 

I 

I 
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Chart  Number  1 

Module  Name  LEOT  CONVERSION 

Date  5/2t/77 


4.  (1.)  Main  Rrooram.  XEDT  CONVERSION 


Rroarawt  bEDT  CONVERSION  <*27  May  77*>  MOO*  V 

^ 32.  LED7  <*aiso  Set  N to  mwiber  of  conditions’^ 

.2/$l  call  poLtACKd,  1#  2»*N)  Ooptimize  tEDT  from 
<*TOPtt1  to  bottomt  L^al  to  RIGHT=2^*N*> 
endprocraa 

2S  erttgy*  a file  of  data  exists  containing  the  LEOT  data. 

This  nroctrain  reads  the  file  into  a structure  modelling  the 
tEDTf  optiSjUes  it  using  the  Pollack  procedure  based  on  minimized 
execution  time»  and  prints  a GRISP  listing  of  the  LBOt 
translation. 


• t Initialize  the  data  structures  lEDT,  ACTION,  A, 

PROS,  GONOXTZON,  and  N with  data  input  as  directed  fay  the 
user. 

• 2 Optimize  the  entire  table,  bounded  at  the  top  by 

condition  row  V,  on  the  left  fay  rule  column  1,  and  oh  the 
right  by  rule  column  Print  a CRISP  cosmetized  listing 

of  the  translation.  If  there  is  an  error  in  the  input  which 
results  in  an  ambiguous  subtabXe,  print  an  error  message, 

” table  entered  in  error". 


I 

r 

a* 
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Module  Number  t*  1 
Module  Name  enter  lbdt 
Date  6/15/77 


<1.  1)  Table  entry  subprogram^  ENTER  LEPT 
On  entryj  the  program  is  uninitialized. 


ti:  This  procedure  declares  and  fills  the  global  data  structures 

i ti,  ACTION,  N,  CONDITION^  RULE,  and  PROS  With  data  input  from  a 

I user-apecif-ied  source-  The  LEDT  array  is  sized  using  N and  then 

I filled  with  the  standard  initialization  described  in  Sections  3 

i and  4*0. 

I Gn  exit-  all  of  the  above  data  structures  are  initialized  as 

i required. 


I The  procedure  for  this  module  is  not  covered  by  this 

i specification.  It  may  conceivably  accommodate  a user  at  an 

i interactive  terminal,  input  from  a file  or  deck  of  cards  in  batch 

[ mode,  or  a combination  of  the  two.  For  this  reason,  such 

\ procedure  is  not  defined  here*  However,  in  any  case,  having 

executed,  this  module  performs  the  indicated  initializations  so 
I that  the  remainder  of  the  program  is  insensitive  to  the  input 

I modev 

i 


i 

i 

< 
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4.  <s  t>) 


Ta^le  process ina  subroutine^ 


Module 

Module 

Date 

POLLACK 


Number  si 
Name  POLLACK 
5/27/7T 


Subroutines  PQL1AGK(T0P,  LErT^r  BlGfW?)  <#27  May  77*>  MGD«  SI 


i 1 

, 2/St 

• 3 

.4/S> 

.5 

.6/S2 

.7/FI 
*8/54 
.9/$5 
. 10/S6 
. 1 1/SI 

• 12 

• 13/S1 
. 14 


. 15 


if  <LEP.T  - RIGHTJ 

call  PRINT  ACTION'ILEFT,  TOP) 

->(TOP  <=  N AND  LEFT  < RIGIW) 

call  CHECK  RULES  (LEFT,  RIGHT,  SAME) 

^ (SAME) 

call  PRIKT_ACTIGK(LEFT,  TOP) 

-Xelse)  * 

let  B=BEST(TGP,  LEFT,  RIGHT.) 

call  EXCHANGE  GONDIT IONS  (TOP,  B.,  LEFT,  RIGHT) 
PARTITION  RULES  (TOP,  LECT,  RIGHT,  MID) 
PRINT  G0ND1TIGN=(T0P,  LEFT) 

POLLACK  (TOP^I,  LEFT,  MID-1) 

PRINT  Else 

POLLACK  (TGP’fri,  MID,  RIGHT) 

PRINT  ENDIP 


call 
call 
call 
32 

call 
do 

.-endif 
->  (else) 

print  error 
• -end if 
end^ufer^ut  ine 


message  "table  entered  in  error" 


on  entry#  the  top  condition  row  and  LEFT  and  RIGHT  rules 
which  bound  the  subtable  have  been  specified*  The  LEDT  contains 
entries  as  described  in  Section  4.0. 


This  recursive  subroutine  processes  the  subtable  of  LEDT 
bounded  by  TOP  and  N (global)  condition  rows,  and  LEFT  and  RIGHT 
rule  columns , and  then  prints  the  CR.ISP  program  for  that  subtable 
using  the  proper  cosmetic  nesting  indxcators. 

On  exit#  the  subtable  program  has  been  printed  and  the  LEDT 
optimized. 

Note:  This  subroutine  is  recursive  in  its  description  here; 

however,  if  the  intended  programming  language  does  not  support 
recursion,  then  an  appropriate  translation  to  iterative  form 
using  a stacK  may  be  substituted* 

.1  If  LEFT  and  RIGHT  coincide,  only  one  action  is 

possible,  so 

,2  print  the  action  text  corresponding  to  LEFT,  using  TOP  to 
compute  the  indentation  level  and  cosmetics. 

,3  If  TOP  is  not  beyond  N and  more  than  one  rule  is  in  the 

table,  then 


9 
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Module  Nuinbet  SI 
Module  Name  POlLAeK 
Date  5/27/77 

.4  examine  the  rules  to  see  if  they  all  invoke  the  same  action:; 
if  sOf  set  SAME  true  (otherwise ^ SAME  is  false) , 

, 5 When  all  actions  are  the  same, 

•6  print  that  action,  as  in  step  , v,  above. 

,7  Otherwise,  the  subtable  requires  refinement-  Hence, 

find  the  best  condition  B in  this  subtable  according  to  the 
cost  criterion* 

.0  Exchange  condition  rows  B and  TOP  between  LEFT  and 

RIGHT 

.9  and  collect  all  rules  with  Y in  the  top  row  occurring 

between  LEFT  and  RIGHT  on  the  left.  Set  MID  to  the  leftmost 
rule  with  an  N entry  in  the  top  row,  or  to  RIGHT+1,  if  none 
occurs. 

.10  Print  “IF”  followed  by  the  condition  text  of  the  TOP 

LEFT  entry  in  the  table,  if  this  is  not  a positive 
condition  number,  there  is  an  error  in  the  table,  and  will 
eventually  cause  an  error  message  at  step  * IS  below; 
Nevertheless,  if  negative,  print  »ngt“  before  the  condition- 

.11  Perform  the  optimisation  of  the  “THEN”  subtable  and 

print  the  “THEN**  clause. 

,12  Separate  with  “(ELSH)"  properly  cosmetized  using  TOP  to 

compute  nesting  level.  (Note;  the  scope  of  variable  of  a 
do  is  the  same  as  the  module  in  Which  it  appears.) 

,13  Perform  optimisation  for  the  “ELSE”  subtable,  print  the 

*»ELSE“  clause, 

,14  and  close  with  “ENDIF”  cosmetized  using  TOP  to  compute 
nesting  level  (see  note  in  step  • 12,  above)  . 

• 15  The  cases  LEFT  ^ RIGHT  with  TOP  > C and  LEFT  > RIGHT 

are  errors  caused  by  improper  table  entry. 


Galled  from; 

1^2 
SU  1 1 
S 1 , 1 3 


10 
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Module  Number  Si* 12 
Module  Name  PR-iNT  ELSE 
Date  ^mni 


4.  (Si*  12)  PPlNrr  the  ELSE  keyword 


TO  PRINT  ELSE  <*27  May  77*>  MOD#  Si*  12 

, 1 “ print  and  four  spaces  for  TOP*1  times;  then 

follow  by  «:->(ELSE)« 
endto 

On  entry*  the  current  value  of  TOP  is  the  nesting  level  of 
the  condition  to  Which  the  ELSE  corresponds. 

This  procedure  prints  the  cosmetics  and  then  (ELSE) 

,1  If  TOP  were  1 then  no  cosmetics  would  precede  the 

so  the  number  of  colon- plus- four- space  repetitions  is  TOp-1* 


11 


■f  ^■ 
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Module  Number  S2 

Module  Name  PRINT  ACTION 

Date  5/27/77 


(S2)  PRINT  the  ACTION  text 


subroutine:  PRINT_AeTION  (LEFT,  TOP)  <*27  May  77*>  MOD#  S2 

.1  print  followed  by  4 spaces r TGP-1  times;  then 

follow  by  the  string  ACTION  {ROLE  (liEPT)  ) 
end  subroutine 


On  entry,  the  applicable  rule  has  been  determined  to  be  the 
value  of  LEFT.  RULE  translates  LEFT  to  an  ACTION  index.  TOP 
indicates  the  nesting  level  of  the  IF  structure  to  Which  this 
action  applies. 

This  subroutine  cosmetizes  and  prints  the  ACTION  text  for 
the  LEFT  RULE  using  TOP  to  determine  indentation. 

-1  LEFT  is  a column  number,  and  RULE  (LEFT)  is  the  action 

index  which  applies.  ACTION  of  this  index  is  the  string 
describing  the  aotion- 


Called  from; 


Sl*2 

Si.  6 


13 
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Module  Ntunber  S3 
Module  Name  CHECK  RULES 
Date  5/31/7T 


4- <S3)  Subroutine  to  CHECK  RULES  for  identical  actions 


Subroutine:  GHEGK_FULE(LEFT,  RIGHT,  SAME)  <*3t  May  77*>  MOD#  S3 

. 1 Set  SAME  ’=  true 

.2  loop  for  i = LEFT  ^ 1 while  fi  5 RIGHT  AMO  SAME) 

• 3 * il  (llULE(i)  # ROLE  (LEFT)) 

.4  f s set  SAME  = false 

f : * .endif 

.5  t , , repeat  with  next  i 

endaubrbatine 

On  entry,  LEFT  and  RIGHT  indicate  the  boundary  of  columns  of 
a subtile*  ROLE  contains  the  action  indices  for  the  subtable. 

This  subroutine  examines  each  of  the  actions  called  for  by 
the  subtable. 

On  exit,  if  the  subtable  has  only  one  action  called  for, 

SAME  will  be  set  to  true;  false  otherwlse- 


, 1 Preset  SAME  to  a true  value  to  serve  as  a structure 

flag, 

• 2r-,5  Iterate  through  the  subtable  from  LEFT  to  RIGHT  until 
ended  or  until  it  has  been  found  to  have  mote  than  one 
action. 

*3  Test  each  rule  against  a fixed  one  (the  LEFTmost)  , 

,4  and  indicate  failure  when  It  occurs. 


Called  from; 


si.  4 
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Module  Number  S4 
Module  Name  EXCRAN«5E 

CONDITIONS 

Date  5/31/77 


«-  (S4)  subroutine  to  EXCHANGE  CONDITION  roWB 


subroutine:  EXCHANGE  GGNDITIGNSITOP,  LEFT,  BIGHT) 

<*3t  May  7T*>  MOD#  S4 

1 - I loop  tor  i - tEET  ^ 1 to  BIGHT 

{ .2  ! ejTchange  t EOT  (TOP, ==  LEDT(:Br  i) 

\ . repeat  with  nesct  i 

\ ends ubr out ine 

I On  entry.  TOP,  DEFT,  and  BIGHT  bound  a subtable  of  LEDT,  and 

! B indicates  the  row  chosen  as  best. 

f 

[ This  Subroutine  interchanges  the  DECT  entries  in  the  TOP  and 

[ B rows  between  DEFT  and  BIGHT. 

5 On  exit,  the  LEDT  subtabXe  has  the  best  row  on  TOP* 

t 

\ *1^.3  Prom  LEFT  to  BIGHT 

\ 

• 2 exchange  row  elements  (the  =^=  operator  signifies  exchange). 


Called  from: 

SI.  B 


Example  L-2  493 


Module  Number  S5 

Module  Name  PARTITION  RULES 

Date  5/31/77 


4,  (S5)  subroutine  to  PARTITION  RULES 


subroutine!  PARTITION  RULESfTOP,  TEPT, 
<♦31  May  T7*> 


. t 
.2 
.3 
*4 

• 5 

• € 


let  MID  = LEFT,  r = RIGHT 
loop  while  (MID  < r) 

! if  (LEDT(TGP,  MID)  > 0) 
( i let  MID  = MlD+1 
I i->(LEDT(TGP,  r)  < 0) 

I j let  r - r-1 


RIGHT,  MID) 


*7 

• 8 

• 9 


10 


f i-Xelse) 

1 t loop  for  i = TOP  by  1 to  N 

! : I exchange  LEDT(1,  MID)  ««  LEDT(i, 

f t ! * # repeat  with  next  i 

! ! exchange  PHOB<MID)  ==  PROB(r) , 

! i RULE  (MID)  ==  RULE|r) 

! : let  MID  » MIDtl,  r = r-1 

f : . ^endif 
! . ■ repeat 
endsUbroutlne 


MODI  S5 


r) 


On  entry ^ the  LEDT  subtabie  bounded  by  TOP,  LEFT,  and  RIGHT 
has  the  best  row  on  TOP, 

This  subroutine  exchanges  columns  until  all  true  (positive) 
entries  of  the  TOP  row  are  on  the  left  of  false  (negative) 
values* 

Qn  exit  * the  subtable  has  been  partitioned,  and  MID  contains 
the  index  of  the  first  false  (negative)  TOP  row  entry  (or 
RIGHTS i#  if  hone  exist)* 

• 1 This  subroutine  begins  by  presetting  MID  to  the  LEFT 

column  and  r to  the  RIGHT  column  of  the  current  subtable, 


•2  and  then  iterates  until  all  columns  having  true  entries  in 
the  TOP  row  lie  to  the  left  of  columns  with  false  entries, 
as  signalled  by  MID  exceeding  r. 

.3  During  this  iteration,  if  the  TOP  entry  in  the  MID 

column  is  already  true* 

•4  increment  MID  to  the  right,  and  repeat.  This  will  continue 
until  the  MID  column  has  a false  TOP  entry  (or  else  until 
MID  goes  beyond  r) . 

*5  If  column  r now  has  a false  entry> 
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Module  Nuniber  SB 

Module  Name  PARTlTION_RUT.ES 

Date  5/31/77 


.6  decrement  r to  the  left  in  search  of  a positive  entry,  until 
a true  column  r is  found  (or  r goes  beyond  MID)  * 

• 7 When  MID  and  r columns  have  thus  been  found,  iterate 

from  the  TOP  of  the  subtable  column  to  the  bottom  {row  K)  * 
(Exchange  from  TOP  to  N is  all  that  is  needed  since  entries 
above  TOP  are  identical  in  the  two  columns.) 

-8  Then  exchange  LEDr  elements  between  columns  MID  and  r. 

.9  Complete  the  column  interchange  by  interchanging 

PRO Babili ties  and  RULES. 

• 10  'Advance  MID  and  r to  the  next  candidates  for 

interchange,  and  repeat. 


Called  from; 
S1.9 
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Module  Number  S6 

Module  Name  PRINT_GGNDITICN 

Date  5/31/77 


(S6)  Subroutine  to  PRINT  the  CONDITION  string 


Subroutine:  PRINT  CONDITION  (TOP,  LEFT)  <^31  May  77 *>  MOD#  S6 

.1  if  (LEDT(TOP^  LEFT)  >0) 

,2  i-  print  •»:"  followed  by  four  spaces,  TOP-1  times:  then 

: follow  by  "IF  ("♦CONDITlONiLEDT(TOP,  LEFT))*")" 

,3  : print  followed  by  four  spaces,  TOP-1  times:;  then 

: follow  by  "IF  (NGT«*G0N0IT10N(-LEDT  (TOP, LEFT))  ♦")  " 

: • ,endi£ 
endsiubrout  ihe 

On  entry.^  the  value  in  the  TOP  LEFT  position  of  LEDT  is  a ♦ 
or  - condition  index  into  the  CONDITION  array.  If  there  has  been 
no  table  entry  error,  this  index  will  be  true  (posit tve)  * 

This  subroutine  normally,  then,  prints  the  corresponding 
OONDITIGN  entry  preceded  by  "IF  ("  and  followed  by  indented 

(using  TOP)  to  the  proper  level,  if  ah  error  has  occurred  and 
the  index  is  negative,  a "NOT"  is  inserted  before  the  predicate* 

An  error  message  will  result  later,  a consequence  of  reaching 
SI.  15. 

On  exit,  the  IF  statement  will  always  have  been  printed. 

.1  Check  the  index  for  a true  value  (positive). 

,2  If  so,  then  print  the  predicate  string  in  an  IF 

statement.  Plus  indicates  concatenation  of  strings. 

*3  If  not,  print  it  anyway,  preceded  by  "NOT". 


Called  from: 
Si.  10 
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Module  Number  F1 
Module  Name  BEST 
Date  5/3V77 


4.  (FI) 


Function  to  pick  the  BEST  row 


Function; 
- 1 
.2 
*3 
,4 
45 

w6 

.7 


p8 


*9 

4 10 
• 11 


4 12 


BEST  (TOP,  LEFT,  RIGHT)  <*31  May  77*> 
let  DBLTAjr^MIN  = infinity 
loop  for  c = TOP  ^ 1 ^ N 

! let  DISGRIM  = 1 , DELTA  T - 0 

loop  for  r j = LEPrti  ^ ^ right 

I loop  for  ri  = LEFT  ^ 1 ^ ^ 


MOD#  FI 


! 

I 

t 

! 

I 

t 

1 

! 

« 

I 

t 

I 

! 

let 


t ! loop  for  k = TOP  ^ 1 to  c*1  to  N 

t ! ! let  DXSeRIM=DISGRIM* 

t ! I (LEDT(k,ri)=LEDT(k,rj>) 

! ! 1 4 4 repeat  with  next  k. 

! f let  DELTA_T«  DELTA  T t 
! ! (PROB{ri)  4.pROB  (r  j)  ) tDlSGRIM 

1 1.4  repeat  with  next  ci 

1.4  repeat  With  next  rj 
let  DELTA  T = DELTA  T * TIME  GOST(c) 
if  (DELTA"T  < DELTA“T  MIN) 

• let  DELTA_T_MIN  ^ DELTA_T,  B = c 
: * ,endif  ” 

, repeat  with  next  c 

BEST  = B <*retujmed  value* > 


endfunction 


On  entry,  TOP,  LEFT  and  RIGHT  tx>und  the  LEDT  subtable  for 
Which  the  BEST  row  is  sought. 


Thin  in t ege r- val ■ j ed  function  computes  the  extra  expected 
times  cbhtfibuted  to  program  execution  by  each  condition  in  the 
subtabie,  and  returns  the  value  of  the  index  of  the  row 
corresponding  to  the  condition  with  least  cost. 


On  exit,  the  LEDT  is  unaltered- 


In  this  procedure  , local  variables  correspond  to  values 
named  in  the  dited  reference  text: 


c 

ri,r  j 
OISGRIM 
DELTA_T 
DELTA  T .MIN 


index  of  condition  being  considered;  integer 

rule  indices  , r j ; integers 

Dc  f r j ) ; real 

AT^;  real 

minimum  aT^;  real 


The  integer  local  variable  B in  steps  .11  and  .12  records  the 
current  Best  index  candidate* 

19 
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Module  Mumber  FI 
Module  Name  BEST 
Date  5/31/77 


• 1 Preset  the  minimuin  cost  metric  to  machine  infinity,  to 

permit  lesser  values  to  be  considered. 

,2  Iterate  through  all  conditions  c left  in  the  subtable. 

• J For  each  new  condition^  preset  the  *»doh*t  care** 

DlsGRIMinant  to  indicate  a <*don^t  care*’  is  possible  so  far^ 
and  set  the  cost  accumuiator  to  tero. 

-4“ -5  For  each  pair  of  rules  rl  and  rj  with  ri  < rj  in  the 

s ub table r 

• 6 and  for  all  conditions  ^ c in  the  subtable, 

,7  compute  the  DIsCJRlMinaht  for  rules  ri  and  rj  over  all  such 

conditions  k.  The  relational  expression  in  this  equation 
takes  a value  1 if  true,  0 if  false. 

.8  Accumulate  the  probaMlity-welghted  DisCRIMinant  into 

the  cost  function  for  condition  c,  over  all  rule  pairs  rx, 
rj- 

• 9 Then  weight  by  the  time^GOST  for  that  decision,  to  give 

the  final  cost  figure*  ~ 

.10  compare  this  cost  with  the  minimum  cost  found  so  far. 

.11  If  less,  replace  the  old  value  with  the  new,  and  record 

the  condition  index  c as  the  Best  candidate. 

-12  After  all  condltiens  have  been  checked,  return  B as  the 

BEST  condition;. 
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• 1 tausworthe^  Robert  C. , standardized  Development  of  Goimputer 
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END  OF  SPECIFIGA1MON 
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EXAMPLE  L-3 

STANDARD  RANDOM  NUMBER 
GENERATOR  FOR  MBASIC^^i 


1.  INTRODUCTION 

1.1  Purpose 

This  document  presents  and  analyzes  a machine-independent  algorithm 
for  generating  pseudorandom  numbers  suitable  for  the  standard  MBASIC'*'*^ 
system.  The  algorithm  used  is  the  “polynomial  eongruential”  or  “linear 
recurrence  modulo  2"  method  devised  by  the  author  in  1965.  Numbers, 
formed  as  nbnoverlapping,  adjacent  28-bit  words  taken  from  the  bit  stream 
produced  by  the  formula  a„^.*.53j  = a.fn+37  ^ (modulo  2),  will  not  repeat 
within  the  projected  age  of  the  solar  system,  will  show  no  ensemble 
correlation,  v/ill  exhibit  uniform  distribution  of  adjacent  numbers  up  to  19 
dimensions,  and  will  not  deviate  from  random  runs-up  and  nms^own 
behavior. 

1.2  Scope 

The  specifications  herein  contained  address  only  machine-independent 
aspects  of  implementation.  Standards  and  conventions,  system  environment 
and  interfaces,  test  and  verification  details  and  other  lower-level 
considerations  are  not  covered:. 

1.3  General  Description 

The  first  MBASIC^*^^  random  number  generator  (Reference  6.1), 
inipiemented  on  the  Univac  1108^  used  a linear  congniential  method 
(Reference  6*2)^  ^ modulo  2^^,  followed  by  normalization  to  the 

range  (04X  This  generator  was  used  probably  because  it  was  already 
available  in  the  U11G8  statistics  package.  Empirical  tests  by  i^ers,  however, 
later  proved  that  the  generator  possessed  veiy  nonrandom  correlation 
properties,  indeed,  especially  if  great  care  were  not  taken  in  specifying  the 
initial  “start”  value. 

This  document  describes  an  alternate  generator  of  a fype  whose 
randbmness  has  been  theoretically  shown  to  be  vastly  superior  and  which 
can  be  implemented  on  any  computer,  despite  word  length  restrictions  (the 
U1108  algorithm  was  tailored  to  36-bit  words).  It  is  a maGhine-independent 
algorithm. 
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The  generation  method  is  almost  as  fast  as  the  linear  congruent iai 
method,  but  not  quite.  The  ratio  of  speeds  is  about  3:  L 

In  1965,  the  author  (Reference  6.3)  showed  that  nunibers  produced  as 
successive  binary  words  of  length  s taken  L bits  apart  (s  < L)  from  a linear 
(shift-register)  bit-stream  recursion  of  the  form 

= Gian_.|  +...+  Gp_ia„„p+l  + a„^p  (modulo  2) 

form  a pseudorandom  sequence  whenever  the  polynomial  f(x)  = xP  + 
Cp_jxP^*  4*...+  ci'X  + 1 is  primitive  over  GF(2).  The  algebraic  structure 
of  these  pseudorandom  numbers  provided  a way  of  proving  that,  over 
randomly  chosen  starting  values  0(),. . t,ap_|  in  the  numeric  sequence,  the 
correlation  between  numbers  is  cssentiafly  zero,  being  ostensibly  equal  to 
^2'*P,  for  all  numbers  iri  the  sequence  separated  by  less  than 
(2P  — s — l)/L,  subject  to  the  restriction  (L,2P  — l)  = 1.  The  author 
further  showed  that  adjacent  k-tiiplcs  of  such  numbers  were  uniformly 
distributed  for  1 :<  k (p/L). 

The  algorithm  for  computing  the  numbers  is  simple,  especially  wh  jn  f(x) 
is  a primitive  trinomial,  say,  xP  + x^  + 1,  where  q < p/2.  An  even  greater 
simplification  is  possible,  and  used  in  this  generator,  when  p is  an  even 
multiple  of  L,  as  is  the  ease  for  the  trinomial  f x^"^  4-  1 (from  Zierler 
and  Brillhard,  Reference  6.4).  The  generator  based  on  this  polynomial  has 
period  1.4  X 10*®®,  has  virtually  no  (average)  correlation  between  any 
numbers  separated  by  distances  less  than  5 X 10^®®,  has  28-bit  precision 
numbers  available,  and  has  adjacencies  up  to  19  dimensions  uniformly 
distributed.  Runs-up  and  runs-down  statistics  up  to  length  16  are 
impeccable.  The  period  and  maximum  correlation  distance  are,  in  fact,  so 
great  that  the  generator  would  have  to  produce  numbers  at  a nmio-second 
rate  for  more  than  lO*'*^  years  before  nonrandom  distribution  or  correlation 
effects  would  be  noticeable  as  nonrandom.  Almost  4 X 10^^  numbers 
would  have  to  be  examined  to  detect  deviations  in  runs-up  and  runs-down 
statistics  as  nonrandom. 


These  pseudorandom  number  generators  have  been  widely  studied 
(References  6.5-6.8)  since  1965,  both  theoretically  and  empirically,  and 
have  been  'promoted  to  pride  of  place  in  the  field  of  pseudorandom 
number  generation  (Reference  6.7).” 

Tootill  (Reference  6;8)  has  eveii  discovered  generators  of  this  type  for 
which  "there  can  exist  no  purely  empirical  tests  of  the  sequence  as  it  stands 
capable  of  distinguishing  between  it  and  [truly  random  sequences].”  For 
reasons  having  to  do  with  computer  storage  and  precision,  the  generator  of 
this  article  iSi  unfortunately,  not  one  of  these.  Nevertheless,  the  generator 
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described  i$  vastly  superior  to  any  linear  congruential  generator  in 
existence. 

The  trinomial  ^ ^ i (having  p ~ 532,  q = 37)  has  several 

things  to  recommend  it:  (l)  532  is  factorable  into  28  times  19,  which  means 
that  19  words  each  having  28  bits  precision  can  be  generated  all  at  once  by 
the  algorithm;  (2)  up  to  and  including  19-tuples  of  adjacently  produced 
random  numbers  will  be  uniformly  distribute;  (3)  28  and  19  are  both 
relatively  prime  to  the  period  — l),  so  no  ill  efltects  occur  as  a result  of 
beginning  new  words  every  28  bits;  (4)  the  period  and  correlation  distance 
are  so  great  as  never  to  be  witnessed  in  the  lifetime  of  the  universe;  and  (o) 
the  q ~ 37  value  produces  good  runs-up  and  runs-down  statistics 
(Reference  6.8)^  up  to  runs  of  length  16. 

2.  THE  METHOD 

The  algorithm  for  producing  the  succeeding  532  bits  from  the  current  set 
of  532  bits  in  the  generator  is: 

(1)  Left-shift  the  current  532-bit  string  by  37  bits,  inserting  37  zeros  on 
right,  dropping  37  bits  on  the  left 

(2)  Add  modulo  2 (exclusive-or),  the  origin^  and  shifted  532  bits^ 

(3)  Right:  shift  this  result  by  532  — 37  = 495  bits,  supplying  495  zeros  on 
the  left,  and  dropping  495  bits  on  the  right. 

(4)  Add  the  results  of  (2)  and  (3),  above,  modulo  2,  to  give  the  next  532 
bits. 

The  proof  that  this  algorithm  works  is  veiy  simple,  and  the  reader  is 
invited  to  apply  the  algorithm  to  the  bit  string  ..Up  and  use  the 
reduction  formula  ap+m  = aj^+m  + ftiy  it  with  a^a2a3a4a5  with  = 
m wnat  is  happening. 

The  BAN00MI2E  function  that  initializes  the  generator  uses  a multipliea- 
tive  linear  congruential  algorithm  to  generate  the  first  19-number  “seed,** 
from  which  the  rest  of  the  generated  numbers  grow.  The  particular  value 
for  the  muitiplier  a in  the  algorithm 

Wn+i  = aw„  (modulo  2*^) 

was  chosen  as  41,475,557  for  the  L = 28  case  from  theoretical  results 
published  in  Ahrens  and  Dieter  (Reference  6,9). 

3.  PUN011ONAL  SPEGIFijDATIONS 

The  random  number  generator  will  consist  of  one  subroutine, 
RAND0Ml2E|storfer) , and  a parameterless  function  RANDOM;  The  starter 
parameter  is  a real  number.  If  the  starter  is  zero,  the  initial  word  wq  is  set 
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to  4X^475,557  (the  linear  congruential  miiltipHer);  if  starter  is  greater  than 
zero,  it  is  converted  to  its  nearest  integer  equivalent,  which  then  becomes 
Wo;  if  starter  is  less  than  zero,  the  computer  clocktime  is  read  and  used  as 
wot  a more  or  less  random  and  unrepeatable  starting  value  for  the 
generator,  randomize  then  generates  18  more  integer  random  words, 
Wj,. . .,Wig  using  the  linear  congruentiai  method  discussed  in  Section  2, 
above. 


The  RANDOM  funetion  returns  a new’  real  value  at  each  invocation,  the  first 
19  of  which  are  generated  by  randomize  above,  and  the  remainder  using  the 
linear  recurrence  algorithm.  Integer  values  used  within  randomize  and 
RANDOM  retain  28  bits  precision.  Values  retunied  by  random  convert  these  to 
real  numbers  in  the  range  (0,lX 

On  converting  28*bit  fixed-point  mantissas  to  real  numbers^  S-digit 
precision  results.  Some  machines,  such  as  the  Univac  1108,  may  have  to 
reduce  this  precision  in  order  to  fit  the  floating-point  exponent  field  into 
the  word  (the  U1 108  has  only  a 27-bit  mantissa  precision).  In  such  cases, 
the  most  significant  bits  of  the  generated  words  shall  always  be  retained  so 
that  all  implementations  produce  essentially  identical  results,  within 
machine  precision.  This  philosophy  is  present  in  the  algorithm  that  follows 
in  Section  4. 

Two  values  of  the  randomize  starter  that  round  to  the  same  internal 
fixed^point  representation  will  produce  the  same  random  sequence; 
conversely,  every  unique  fixed-point  representation  of  the  argument 
produces  a unique  random  sequence.  In  addition,  so  long  as  the  value  of  the 
argument  is  the  same  and  stays  within  the  precisions  of  two  dififering 
machines,  the  sequences  produced  on  each  will  be  the  same,  within 
machine  precision. 

4.  PROGRAMMING  SPECIFICATION 
4.0  Overview 

Managing  the  532-bit  shift-register  is  the  main  trick  in  implementing  the 
method.  The  algorithm  given  in  this  section  utilizes  an  array  Wj, 
i = 0^, . .,18  of  b-bit  computer  words  (b  ^ 28)  sufficient  to  encompass  the 
532  span  of  bits  to  he  operated  on  (and  retained),  and  delivered  in  28-bit 
chunks  whenever  the  random  function  is  invoked. 

On  machines  having  word  sizes  smaller  than  28  bits,  double  (or  multiple) 
words  will  have  to  be  used  for  each  word  in  the  algorithm  below.  XOR  in 
the  RANDOM  function  below  signifies  an  "e^Stclusive^QR”  of  the  operand 
binaiy  words. 
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Module  Number  1 

Module  Name  randomize 

Date  6/15/77 

4.(1)  The  RANDOMIZE  Subroutine 

Subroutine:  RANDOMIZE  Cs tar ter: real) 

<*  This  function  declares  and  initializes  a 19- element 
<•  array»  w|d]  , , * , * w [18]  witb  random  numbers  generated 
<•  by  a linear  cpngruential  method.  An  integer  1 is 
<■♦  set  to  zero  to  enable  RANDOM  to  select  w [O]  as  the 
<♦  first  random  number.  I and  w are  permanent  data 
<*  structures,  accessed  only  by  RANDOMIZE  and  RANDOM. 

.1  constant  multiplier:  integer  = 414755'57 

. 2 variable  J : integer,  I: integer, 

w:  array  (0. . 1'8]  of  universal  integer 

.3  if  (i s t a r te  r < O) 

.4  : start:  «-clockti me<*re turns  current  time  of 

: <*day  as  integer*> 

. 5 : ->  (!Starter=Oj) 

.6  : start:  =iiiu  I tipi  ier 

: - > (el'Sei)  < ♦ st  art  e r > 0 • > 

.7  : start' —fix  (starter)  <*floaiting-to-lriteger 

; <*convorsion*> 

; . . endi  f 

.8  w(0]:  "Start 

. 9 loop  for  j = 1 to  18 

.to  I w(j]  " fw  [j“i]  ^multiplier)  modulo  2**28 

• 11  1 * • repeat  with  next  j 

.12  1 " 0 <«set  up  to  pic-k  w [0]  as  first  random  number*> 

endsubroutljne 
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Module  Number  2 

Module  Name  random 

Date  6/15/77 


4.(2)  The  RANDOM  Function 


Function'.  RANDOM*,  real 

<•  This  algorithm  makes  use  of  a 19 -word  array, 

<♦  w (Oj w (M] , each  with  b bits. 

<•  Each  word  contains  precisely 

<^*  28  bits  of  the  generator,  right  justified.  A local 
<•  integer  variable  I on  entry  contains  the  index  of 
<♦  the  word  next  to  be  returnee!  as  the  random  value. 

<•  Both  w and  I are  permanent  data  structures,  accessed 
<*  only  by  RANDOM  and  RANDOMIZE,  The  latter  of  these 
<•  initializes  1 to  zero  and  w to  the  seed. 


. 1 

.2 
. 3 
. 4 
.5 
*6 
. 7 
,8 

.9 
. 10 
. 11 


. 12 
. 13 
. 14 


. 15 
. 16 
. 17 

. 1;8 
, 19 


variable  j: integer 

if  (I«19)  <*ali  words  have  been  used  up*> 

1 :=  0 <*reset  to  first  element  in  array*> 

' ^ 16  <•  ex  elude  last  two  words*> 

: I load  w(j+1]  , w [j+2]  into  registers  AO,  A1 

: ! left  shift  A1  by  b-28  <*join  bits  In  stream*> 

! left  shift  A0.A1  by  9 <*q-^37  is  26+9*> 

: ' w(j]  :=  (w-[jj  XOR  AO)  <*the  recursion 

i <*formula*> 

* ! . . repeat  wl t h nex  t j 

: load  w [18]  . w [o]  into  A0.A1  <*now  compute  w [17]  :♦> 

: left  shift  A1  by  b-28  <*join  wfie|,  w(=o] 

<*bit  St  reams  *> 

: left  shift  A0,A1  by  9 

: <»AG  now  has  final  19  bits  of  w [is]  ♦> 

: w [17]  :=  w [17|  XOR  AO 

: <*and  first  9 bits  of  stream  shifted  495*> 

: load  w fO]  , w[lj  into  A0.A1  cfdo  similarly 

<»f  or  w 1:18]  *•> 
left  shift  A1  by  b-2B 
left  shift  AO.  A1  by  9 
W [18]  :=  < W |18]  XQR  AO  ) 

: . , endif 

RANDOM  ^ f loat  fw  [I] ) /2**28  <♦  convert  to  real»> 

I :=  X+1 
endfunction 


' - ^ I- 
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5.  ANALYSIS  AND  EVALUATION 

Note  in  the  method  that  the  number  of  computations  required  for 
generating  the  next  p bits  grows  at  most  linearly  in  p.  Assuming  p»  L, 
then  partitioning  the  p generator  bits  into  words  of  length  L produces  a 
number  of  words  that  ako  increases  in  proportion  to  p.  Therefore,  the 
number  of  computations  for  L-bit  precision  random  numbers,  to  first-order 
eflFeets,  is  independent  of  the  recursion  degree  p.  Making  p large,  however, 
has  advantages  in  increasing  randomness  properties. 

It  is  true  that,  as  p increases,  more  and  more  registers  are  required  to 
compute  each  new  set  of  p bits,  and  shifting  many  registers  at  once  presents 
a small  inconvenience  in  most  computer  languages.  These  factors  place  a 
smalt  speed  and  storage  overhead  on  the  generation  process;  but  even  this 
is  not  extreme  due  to  the  particular  trinomial  chosen. 

Counting  the  number  of  elemental  operations  (loadj  store  shift,  etc.)  for 
the  algorithm,  one  finds  about  10  + f operations  per  number  generated, 
where  f is  the  number  of  operations  in  ‘‘floating"  the  fixed-point  number. 
The  linear  congruential  algprithm  requires  only  about  3 + f such 
operations,  so  the  ratio  of  speeds  is  less  than  3:1, 

The  RANDOM  function  is  about  23  + f operations  long,  as  coriipiic  d to 
3 + f for  its  linear  congruential  form,  and  data  storage  is  21  words  versus 
2.  However,  even  though  the  program  requires  perhaps  7 times  as  much 
storage  as  the  linear  congruential  form,  the  total  is  still  probably  under  50 
locations,  of  negligible  concern  in  most  installations.  The  asymptotically 
random  sequence  of  Tootill  (Reference  6^8)  requires  607  words  to  store  the 
w -array  alone.  (This,  coupled  with  the  fact  that  only  23-bit  precision  was 
available  in  that  generator,  is  why  it  was  not  considered  here.) 

The  algorithm  given  has  been  implemented  as  the  random  function  in  the 
MBASIC^^  processor  currently  on  the  Caltech  PDP-10  and  the  JPL  Univac 
1108  computers.  All  tests  run  on  it  so  far  validate  the  randomness 
propeities  claimed  by  the  theory.  In  that  theory,  by  the  way,  the  only  factor 
left  to  chance  is  the  specification  of  the  initial  ‘‘seed,"  The  stated 
uniformity,  zero-correlation,  and  runs  statistics  are  all  based  on  the  single 
assumption  that  the  seed  be  chosen  randomly,  Of  course,  the  default  value 
canned  in  was  not  randomly  chosen,  but  chosen  speGifically  to  took  random 
except  for  the  first  word  and,  certainly,  to  the  extent  of  the  tests  run,  this 
appears  to  have  worked  beautifully. 

It  was  also  demonstrated  that  the  generator  is  also  capable  (as  b every 
known  random  number  generator)  of  producing  numbers  with  3-sigma 
variations  from  randomness  over  a few  thousand  samples  when  the  wrong 
seed  is  supplied^ 
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As  a coding  check  on  the  algorithm,  the  following  40  numbers  suffice  to 
establish  probable  correctness^ 


.1543085 

— ►.6206040 

I— ►.2185256 

— ►.7161612 

.6887634 

.6988867 

,3544603 

.9263908 

.7998630 

.3691845 

.6903309 

.9220639 

.1906013 

.8255893 

.0641026 

.9966978 

.7919956 

.4282176 

.3321068 

.6469416 

.8004964 

.5929163 

.6594338 

.9405825 

.9601586 

.8871027 

.6285133 

.6677605 

.1921166 

.3302294 

.4838374 

.8933217 

.9015029 

.2870978 

.2324675 

.3779590 

.51i68044 1 

.3091386 

.3086822 1 

.2973689 

The  first  19  of  these  are  the  generated  '*seed,”  and  the  remaining  21  are  the 
results  of  Gombihing  the  stored  numbers  according  to  the  method  given. 
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EXAMPLE  L-4 

RANKING  COMPETING  FACTORS  BY 
WEIGHTED  DOMINANCES 


1.  INTRODUCTION 

1.1  Purpose 

This  program  rates  a set  of  competing  factors  using  weighted  first-  and 
second-order  dominanGe  scores  derived  from  pairwise  comparisons  and 
weights  input  interactively  by  the  user,  and  then  prints  a ranked  list  of  the 
factors  with  scores. 


1.2  Scope 

The  descriptions  contained  herein  address  only  machine-independent 
aspects  of  implementation.  Standards  and  conventions,  environment  and 
interfaces,  test  and  verification  details,  and  other  lower-level  considerations 
are  not  covered. 

1.3  General  Description 

Given  N factors  that  are  to  be  ranked  in  order  of  importance,  a pairwise 
judgment  of  the  importance  of  one  factor  over  another  is  called  a first-order 
dominance*  The  number  of  times  a particular  factor  dominates  among  the 
N — 1 other  factors  is  the  first-order  dominance  score  for  that  factor. 

A second-order  dominance  between  two  factors,  say*  i and  k,  is  said  to 
exist  if  there  exists  another  factor  j such  that  i dominates  J,  and  j dominates 
k (in  this  case  i exhibits  a second-order  dominance  over  k).  Second-order 
dominanGe  strength  is  defined  as  the  number  of  such  j that  can  be  found  for 
given  i and  k.  The  second-order  dominance  score  for  factor  i is  the  sum  of 
the  strengths  of  all  second^order  dominances  of  i over  other  factors. 


The  above  definitions  make  it  impossible  for  a factor  to  exhibit  either 
first-  or  second-order  dominance  over  itself.  Third-  and  higher-order 
dominances  can  similarly  be  defined  and  eomputed;  however,  they  are  of 
questionable  utility,  since  they  raise  a philosophical  problem,  namely,  that 
It  is  possible  for  a factor  to  exhibit  a thirds  or  higher-order  dominance  over 
itself.  Although  such  calculations  are  straightforward,  computation  of  thirds 
and  higher-order  dominances  are  not  included  in  the  program  capability 
described  here. 
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First-  aRd  second-order  scores  can  then  be  weighted  and  summed  jto 
compute  weighted  dominances  for  various  purposes.  The  proper  weighting 
factors  for  decision  making  are  probably  best  determined  by  experimenta- 
tion. Generally,  first-order  dominance  scores  provide  a veiy  reliable 
ranking,  and  second-order  scores  can  be  used  to  add  weight  to  this  ranking, 
or  to  break  ties,  or  possibly  to  check  the  validity  of  the  first-order  results.  If 
second-order  dominances  cause  the  rankings  to  change,  the  results  may  be 
suspect  with  regard  to  the  rigor  or  true  priorities  that  apply  among 
competing  factors. 

An  elementary  discussion  of  dominance  methods  and  their  applications  to 
behavioral  science  problems  is  given  by  Keineny,  J.  G.,  Snell,  J.  L.,  and 
Thompson,  G.  L.,  in  Introductioti  to  Finite  Mathematics^  Second  Eklition, 
Prentice-Hall,  Inc.,  1966. 


2.  THE  METHOD 

Let  N denote  the  number  of  factors  to  be  ranked,  and  let  First-order 
dominances  be  recorded  in  an  N X N matrix  F by  setting  f^  = 1 if  factor 
i is  preferred  over  factor  k,  and  = 0 otherwise.  The  sum  of  the  entries 
in  the  ith  row  is  then  the  first-order  dominance  score  for  factor  i. 

In  the  matrix  S = F^,  the  element  will  be  equal  to  the  number  of 
times  that  a Second-order  dominance  of  i over  k exists,  and  is  hence  the 
strength  of  that  dominanca  The  sum  of  the  entries  in  the  ith  row  of  S is 
then  the  secondrorder  dominance  score  for  factor  i. 

If  Wi  and  W2  are  scalar  weights  input  by  the  user  and  U is  a 1 X N all- 
ones  vector,  then  the  Resultant  weighted  score  vector  R is  governed  by  the 
matrix  equation 

R = (wiF  + W2S)U 


a FUNCTIONAL  SPECIFICATIONS 

The  RANKING  program  operates  in  an  interactive  mode  as  presumed  by 
this  specification;  suitable  translation  may  he  made  to  accommodate  batch 
operation. 

The  user  is  prompted  to  input  the  number  of  factors  to  be  ranked, 
followed  by  a request  to  input  an  equal  number  of  short  descriptive  strings 
that  identify  these  factors.  Then,  the  program  prompts  the  user  to  enter  a 
judgment  between  pairwise  alternatives  for  each  pertinent  pair  of  factors. 
The  program  names  the  factors  to  be  judged  before  each  judgment  entiy  is 
made. 
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When  all  dominances  have  been  registered,  the  program  asks  for 
weighting  factors  to  be  entered  and,  upon  receiving  these,  prints  the  first- 
order,  second-order,  and  weighted  dominance  scores. 


I; 

1} 
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The  following  example  specifies  the  format  of  input  and  output  dialogue. 
User  entries  are  distinguished  by  the  lighter  ^e;  the  character  'Vcr” 
denotes  a carriage  return.  A signals  that  a user  entiy  is  required^ 


ENTER  THE  NUMBER  OF  FACTORS  TO  BE  RANKED:  >4 
NOW  NAME  THESE  4 FACTORS: 

> RELIABILITY  ^cr 

> SPEED  .(-cr 
>STORAGE.^or 

> DOCUMENTATION  .e-cr 

NOW  RANK  PAIRS  AS  FOLLOWS: 

ENTER  THE  NUMBER  (1  OR  2)  OF  FACTOR  PREFERRED. 
RELIABILITY  OR  SPEED? 

^1  4-cr 

RELIABILITY  OR  STORAGE? 

RELIABILITY  OR  DOCUMENTATION? 

>1  ^cr 

SPEED  OR  STORAGE? 

^ 1 4-cr 

SPEED  OR  DOGUMENTATiON? 

>■2  ^-cr 

STORAGE  OR  pOCU MENTATION 7 


! 

I 

i 


4 

i 

i 

f 

i 

I 

i 


i 

i 


>2 

NOW  ENTER  TWO  WEIGHTS  SEPARATED  BY  COMMA. 

>1.0,0.  5<-t_T 


banking  of  factors 

IS  AS  FOLLOWS; 

j 

FACTOR 

FIRST 

SECOND 

WEIGHTED 

if 

RELIABILITY 

3 

3 

4.  5 

• ^ 

DOCUMENTATION 

2 

1 

2,  6 

SPEED 

1 

0 

1.0 

STORAGE 

0 

0 

0.0 

i 

i 

DO  YOU  WANT  TO  TRY  ANOTHER  WEIGHTING?  >NO.^c!- 


(program  terminates) 


\ 
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The  program  shall  accept  up  to  20  characters  for  each  factor  name.  The 
number  of  factors  and  preferences  must  be  integers.  Weights  are  real 
numbers^  The  request  for  another  weighting  shall  be  answered  either  yes  or 
NO. 

If  a YES  is  entered,  the  resulting  program  dialogue  shall  appear  as  above 
from  the  “NOW  ENTEft  two  WEIGHTS. . line  on  down. 


Data  type  errors  in  user  input  are  not  checked  by  this  program;  reeoveiy 
from  such  errors  shall  be  configured,  as  can  be  best  accommodated  in  the 
implementation  language,  so  as  to  reprpmpt  the  user  for  correct  entry. 

4.  PROGRAMMING  SPECIFICATION 

4X>  Overview 

On  execution,  the  program  records  the  number  of  factors  to  be  ranked  in 
an  integer  variable  n and  the  factor  names  iil  a string  array  FACTOR,  which 
can  hold  N 20-character  entries.  Dominance  values  are  recorded  in  the  N X 
N matrix  FIRST;  squaring  FIRST  yields  SECOND.  Three  N X 1 arrays  ACGUMi, 
AGGUM2,  and  AGGUMW  hold  evaluations  of  first-order,  second-order,  and 
weighted  dominances,  respectively. 

Another  N X 1 array,  INDEX,  holds  the  indices  that  match  entries  in  the 
ACCUMW  array  to  the  FACTOR  names  and  AGGUMi  and  AGCUM2  values.  Then  the 
ACGUMV^  and  index  arrays  are  sorted  in  decreasing  order  using  AGCUMW  as  a 
key.  Printing  of  names  and  dominances  proceeds  in  this  sorted  order 
(agcumi,  ACGUM2,  and  F^AGTOR  are  addressed  via  INDEX  in  this  printing). 

Note:  In  programming  languages  that  permit  record  data  structures,  then 
an  array  of  N records  with  factor,  agcumi,  agcum2,  and  aggum  fields  on  each 
record  can  be  sorted  on  the  ACCUMW  field,  in  wliich  case,  index  \s  not 
required^ 
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Module  Number  1 

Module  Name  ranking 

Date  6/15/77 

4.(1)  The  RANKING  Program 

RANKING 

p romp t-a  nd^ln  pu  t_N 
decia  re_3  torage^ar  rays 
© n t e r_f a c t o r_n  am e s 
enter-dominancas 

c ompu  t e„f  1 r s t-an  d_s  e co  n d^o  rder_d  om  In  an  c gi^$  co  res 
loqp 

! c ompu  te_weighted-.domi  nances 
! print^report 

\ p romp  t_f  o r_ano  t h e r-w©  i g ht  1 ng_and_ac  cep.t_ANSWER 
I ..repeat  ^ (ANSWER  = *YES') 
end program 

.1  Declare  an  integer  variable  N,  print  the  message  '‘enter  THE  NUMBER 
OF  FACTORS  TO  BE  RANKED;  accept  the  value  of  N,  and  check  to  assure 
N > 2;(the^highest  order  of  dominance),  Beprompt  and  reaceept  N if  N 
< 2 ^Vas  entered. 

.2  Declare  the  rest  of  the  data  structures  used  in  the  program.  In 
li^giiages  that  permit  dynamic  dimensioning  of  arrays,  these  arrays 
can  be  dimensioned  to  N in  size.  Otherwise,  an  array  dimension  larger 
than  the  envisioned  range  of  n must  be  chosen.  The  declarations  are: 
FACTOR  i;N]:  String  of  20  characters;  INDEX  [N]  , AGGUMI  [n]  , ACCUM2[N;], 
FIRST  In.  N],  SECOND  [n.n]  are  integer  arrays;  AGGUMW  fN.N]  is  a real 
array;  i and  J denote  integer  indices  for  these  arrays;  Wi  and  W2  are 
real  variables;  and  answer  is  a string  variable  capable  of  holding  up 
to  three  characters.  Initialize  INDEX  [i]  = i for  i = 1 to  N,  so  as  to 
record  index-torpositipn  information  for  later  sorting. 

.3  Prompt  with  the  message  "Now  NAME  THESE  " + str(N)  + 
" FACTORS: ",  where  STR  is  an  mteger-to-string  conversion j and  accept 
entry  of  N strings  from  the  user  into  the  FACTOR  name  arrays 
prompting  by  “ >”  before  each.  above  is  string  concatenation. 

A Print  the  message  "NOW  rank  pairs  as  FOLLOWS:  " followed  by 
"ENTER  THE  NUMBER  (1  OR  2)  OF  FACTOR  PREFERRED.  " Then  for  each  pair 
of  indices  i,  j with  i > j,  prompt  with  the  message  FACTOR  [i]  + 
" OR  " + FAGTGR:[JJ  + then  a carriage  return  and  " >",  and 

accept  1 or  2 (reprompt  if  entry  is  not  1 or  2).  Set  first  [i, and 
FiRSTi  j , tj  to  0 and  1 to  record  dominance  properly. 


Program: 
. 1 
.2 
.3 
-4 
. 5 
. 6 
. 7 
. 8 
.9 
. 10 
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Module  Number  1 

Module  Name  ranking 

Date  6/15/77 


.5  Square  the  matrix  first  and  store  result  in  second.  Sum  the  rows 
of  each  and  insert  results  in  ACGOMi  and  ACGUM2  arrays,  respeGtively. 

.6  Then,  to  accommodate  several  weighting  factors,  if  desired, 

J prompt  user  with  the  message  “NOW  ENTER  TWG  WEIGHTS  SEPARATED  by 
COMMA.  “ followed  by  a carriage  return  and  >“.  Then  accept  real 
weights  wi  and  W2,  compute  weighteil  dominances,  and  store  these  in 
ACCUMW. 

^8  Sort  the  ACCUMW  array  in  descending  order  of  value  from  acgumw  [t  j 
to  AGGUMW  fNj;-  Use  the  Bubble'Sort  technique  {ef.  Example  7.3.3.1  in 
Part  1 of  this  text,  but  replace  “>’*  by  "<*"  in  the  “elements,  . .our  OF 
ORDER”  macro).  Then  print  the  report  header  shown  in  Section  3^ 
followed  by  FACTOR  [INDEX  [i]  J , ACGUM  [INDEX  [1]  ] , ACCDM2  [INDEX  fij)]  , 
and  AGCUMW  [i]  for  i = 1 to  N, 

,9  Print  the  message  “DO  YOU  WANT  To  TRY  ANOTHER  WEIGHTING?  >", 
and  accept  answer  as  ”VES“  or  "NO”.  Reprompt  if  anything  else  is 
entered, 

.10  Repeat  from  step  6 if  another  weighting  was  desired;  otherwise 
terminate  execution. 

END  OF  SPECIFICATION 
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USEFUL  STANDARD  FORMS 


The  23  forms  contained  in  this  final  appendix  are  typical  among  those 
commonly  in  use  in  medium-  and  larger-scale  software  projects.  These  are 
forms  for  project  planning  and  management,  functional  design,  status 
reporting,  configiiration  management,  and  quality  assurance.  The  use  of 
such  materials  constitutes  what  some  have  termed  a “forms  approach^’  to 
software  development,  which  mirrors  practices  used  in  almost  eveiy 
successful  engineering  and  business  endeavor.  Depending  on  the  size  and 
intended  lifecycle  of  the  software,  the  need  for  the  information  such  fbrhis 
contain  is  real,  not  the  mere  whim  of  an  administrator  whose  lust  tends 
toward  rigid  formal  measures  and  banal  routine  procedures.  Properly  done^ 
the  use  of  forms  in  software  development  tends  to  standardize  interfaces 
among  people  and  aciess  organizational  lines,  and  can^  at  the  same  tlme^ 
serve  to  turn  “paper  work“  into  “working  paper/*  Most  of  the  forms  shown 
in  this  appendix  can  most  assuredly  be  computerized,  both  in  the  process  of 
eolleeting  the  data  required  to  fill  them  out,  as  well  as  in  the  processing, 
output,  and  distributicn  of  those  data  to  their  intended  ends. 

However,  whether  such  forms  as  these  are  eventually  computerized  or 
not  for  project  usage  will  depend  largely  on  how  each  of  the  selected  forms 
seems  to  interface  most  effectively  with  the  conglomerate  of  human 
activities  for  which  it  is  ir tended,  Forms  are  viewed  as  media  of  expression 
in  the  design  process,  of  working  documentation  during  software 
construction  and  test,  of  communication  among  team  members,  of  status 
monitoring  and  project  control  during  implementation,  and  of  historical 
value  for  the  future.  New  forms  may  be  added  with  the  same  goals. 

The  forms  here  are  presented  without  explanation  as  to  theii*  exact 
recommended  usages  the  specific  meaning  of  the  blanks  requiring  entry  by 
the  user,  the  criteria  for  use  or  interpretationj  standards  for  nomenclature 
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and  coding  of  identifiers,  or  the  procedures  to  be  followed  to  make  the 
forms  efi^tive.  I do  not  mean  to  imply  by  this  omission  that  I believe  the 
forms  are  self-explanatoiy  (even  though  strived  for),  not  needing  such 
accompanying  documentation  for  fully  eifective  and  non-ambiguous  use. 
Nor  do  I contend  that  the  set  of  forms  given  is  a complete  and  sufficient  set 
of  such  materials  needed  by  a project.  Some  projects  may  need  more^  some 
less. 

Rather,  the  forms  represent  examples  upon  which  project,  organization, 
or  industry  standards  are  or  can  be  built.  They  further  illustrate  the  types  of 
information  required  by  programmers,  managers,  QA  personnel,  and  others 
associated  with  the  software  being  developed  in  coping  with  their  own 
various  and  diversified  tasks. 

The  forms  of  this  appendix  find  their  origins,  both  in  format  and  content, 
in  several  JPL,  Militaiy/DQD^  and  industry  sources,  I have  extendied  some 
of  these  forms,  simplified  others,  and  merely  translated  or  rearranged  still 
others,  so  that  all  of  the  exhibited  forms  bear  a hoped-for  family 
resemblance. 


Software  Technical  Progress  Report 


Tide: 

Task  Mgr:  Phone: 

talk: 

Identifier: 

Date: 

Period:  to 

Statu  sSummarv 

% Complete: 

HffnH  TO  campiete:  — 

Remaining  Resources:  

Probrenis 

Schedule  impact: 

Fbrecan 


R«ource»: 

Name 


Futtctfon 


Effort/other 

expenditure 


Accomplishments 


text 

flpvuchem 

figures 

tsblei 

code 

test 


thii  report 

cumulative 

1 ffnaf  iert) 

percent  <e$t) 

units 

effort 

units 

effort 

units 

effort. 

units 

effort 



~ 

zz 

zz 

Schedufed  completion  date. 


Prepared!by 


Software  Anomaly  Report 


Softwareiitem; 

Anomaly  Npj 

SWIO; 

Ihltigtediby: 

Phone; 

: Date: 

Versfph 


Gontio/as 


CatPfjpf 


Detects  Date  jRwpofne  patt| 


Log  Date 


neferancas 


Problem ' Description  {(ymptoma  and  conditions  of  occurrence^ 


Data 


Teat.  Prodedure 


Te»t  Version 


Artachmenr:  Ye*0  No  □ 


SuBpected  Cause,  Comments.  andiRecommencfotlpn 
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Specification  Change  Notice 


; Software  Item; 

— — ^ — — 

— — 

SW  tP; 

■■ 

Pete: 

^ Ivsupd  bv; 

Phone: 

Version 

Config/6s 

Recipientsof  this  mtice  arsthereby  informed  that; the  spectfications 
referenced  abowe  have  been  chang^.  Description?  of  the: changes  are 
(oggedlbelow  and  materials  for  effect  mg  said  changes  are  turnishcdfferewHh. 

SSD  Section 


ChangeOrder 

1 Effective 

hio. 

bate 

SpftvwareJtem: 


SWIO: 


Audited^by: 

Phone: 

pate: 

Version 

1 

jCbnfig/oS 

Control  Date 

Audit  Dale  • 

.Audit  Type  | 

: Audit  Method 

ReferenCTS 


Items  Audited 


DIscropancie^EKceptilbnE 


StatusSummary 


'Signature 


iOatfi 


Signature 


Date 
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Sofwvarfl  Item: 


Software  Standard' Waiver 

Waiver  No.: 


SWIO: 


I 

I 


Raqu«ied=by.; 

Description  of  Standafd'lQ.be:Wa1ved 


Phone: 


Date: 


Scope  of  Waiver  {items  to  which  waiver  applies! 


Justification  and  Analysis 


I 


Proposed  Altemate:to  Standard 


Action 

Disapproved 

□ 

Grounds 

Comments 

Approved 

□ 

Proviso 

Signature 


bate 


Signature 


bate 
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Project: 

Task: 

Identifier: 

Date: 

MILESTONES 

r 1 :i  i 

1 „ ■ 

IIIHIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII 


liiiiii 

IlllllllllllllllillllllllUlllillllllllW^ 

IHIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIHIIIIIIIIII 

iiiiiiiiiiiniiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiuiiniii 

iiiuiniiiiiiiiiiiiiiiiiiiiiniiiiHiiiiiiiiiiiiiiiiiiiiiHi 

iiiiniHiinii 


IIIIIIIIIIIIIIIIIUIIIIIIIIIIIIIIIIIIIHIIIIIIIIIIIIIIIIIIIII 

IllllllllllUlllllllllllllllllllllllillllllllllllllllllllllli 

lillllllllllillllllilllllllllllllUllllllllllllilllllllllllll 


Legend  ft^rkcn  vyKro  accomptishedl: 

Ofnput  due  V ResqhetJuletf  milestone 

A OrJ^nal  mjl^one  ^ Deliver^  Item 


Work  force 
Work  planned 
Reschecitiled  work 
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